Add Backup / Restore docs

modules/administration-guide/nav.adoc

@@ -1,5 +1,5 @@
 .Administration Guide
-        
+
 * xref:che-architecture-overview.adoc[]
 ** xref:che-workspace-controller.adoc[]
 ** xref:che-workspaces-architecture.adoc[]
@@ -24,8 +24,13 @@
 * xref:tracing-che.adoc[]
 
 * xref:backup-and-disaster-recovery.adoc[]
-** xref:external-database-setup.adoc[]
+** xref:setup-backup-server.adoc[]
+** xref:managing-backups-through-cli.adoc[]
+*** xref:configuring-cli-to-use-backup-server.adoc[]
+** xref:managing-backups-through-custom-resources.adoc[]
+*** xref:define-backup-server-for-operator.adoc[]
 ** xref:persistent-volumes-backups.adoc[]
+** xref:external-database-setup.adoc[]
 
 * xref:caching-images-for-faster-workspace-start.adoc[]
 ** xref:defining-the-list-of-images-to-pull.adoc[]

modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc

@@ -0,0 +1,7 @@
+[id="configuring-cli-to-use-backup-server"]
+// = Managing backups through CLI
+:navtitle: Configuring CLI to use backup server
+:keywords: administration-guide, backup, recovery, cli
+:page-aliases: .:configure-cli-to-use-backup-server
+
+include::partial$proc_configuring-cli-to-use-backup-server.adoc[]

modules/administration-guide/pages/define-backup-server-for-operator.adoc

@@ -0,0 +1,7 @@
+[id="define-backup-server-for-operator"]
+// = Defining backup server for operator
+:navtitle: Configuring {prod-short} Operator to use backup server
+:keywords: administration-guide, backup, recovery, operator
+:page-aliases: .:define-backup-server-for-operator
+
+include::partial$con_define-backup-server-for-operator.adoc[]

modules/administration-guide/pages/managing-backups-through-cli.adoc

@@ -0,0 +1,7 @@
+[id="managing-backups-through-cli"]
+// = Managing backups through cli
+:navtitle: Managing backups through cli
+:keywords: administration-guide, backup, recovery
+:page-aliases: .:managing-backups-through-cli
+
+include::partial$proc_managing-backups-through-cli.adoc[]

modules/administration-guide/pages/managing-backups-through-custom-resources.adoc

@@ -0,0 +1,7 @@
+[id="managing-backups-through-custom-resources"]
+// = Managing backups through custom resources
+:navtitle: Managing backups through custom resources
+:keywords: administration-guide, backup, recovery
+:page-aliases: .:managing-backups-through-custom-resources
+
+include::partial$proc_managing-backups-through-custom-resources.adoc[]

modules/administration-guide/pages/setup-backup-server.adoc

@@ -0,0 +1,7 @@
+[id="setup-backup-server"]
+// = Setting up a backup server
+:navtitle: Setting up a backup server
+:keywords: administration-guide, backup, recovery, backup-server
+:page-aliases: .:setup-backup-server
+
+include::partial$con_setup-backup-server.adoc[]

modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc

@@ -7,9 +7,23 @@
 
 :context: backup-and-disaster-recovery
 
-This section describes aspects of the {prod-short} backup and disaster recovery.
+
+{prod} Operator can create backups of {prod-short} instances and restore them from a backup snapshot if needed. The following chapter describes ways of preparing such backups and their use in the follow-up recovery phase:
+
+* xref:managing-backups-through-cli.adoc[]
+* xref:managing-backups-through-custom-resources.adoc[]
+
+
+[CAUTION]
+====
+* The standard backup mechanism of {prod-short} does not back up the content of users' workspaces. To preserve local changes, see xref:persistent-volumes-backups.adoc[].
+
+* Backup snapshots are bound to their own specific cluster and must be used only there.
+====
+
+.Additional resources
+
 
 * xref:external-database-setup.adoc[]
-* xref:persistent-volumes-backups.adoc[]
 
 :context: {parent-context-of-backup-and-disaster-recovery}

modules/administration-guide/partials/con_define-backup-server-for-operator.adoc

@@ -0,0 +1,99 @@
+[id="define-backup-server-for-operator"]
+= Configuring {prod-short} to use backup server
+
+
+To configure a backup server for {prod-short}, a user needs to create the `CheBackupServerConfiguration` Custom Resource object in the {prod-namespace} namespace. The object's `spec` property is divided in several sections where each corresponds to a specific xref:setup-backup-server.adoc[backup server type]:
+
+ * xref:configure-rest-server-cr[REST]
+ * xref:configure-awss3-server-cr[AWS S3 or API compatible]
+ * xref:configure-sftp-server-cr[SFTP]
++
+[NOTE]
+====
+* The Custom Resource object, stored in the `{prod-namespace}` namespace, must have only one section configured in the `spec` property.
+
+* It is possible to configure as many backup servers as needed, but each in a separate `Custom Resource`.
+
+* Referenced secrets for each server type must exist and have required fields specified. See the description of each secret in the corresponding server-type chapters.
+====
+
+[id="configure-rest-server-cr"]
+== Configuring REST server
+
+[source,yaml,subs="+attributes"]
+----
+apiVersion: org.eclipse.che/v1
+kind: CheBackupServerConfiguration
+metadata:
+  name: backup-server-configuration
+spec:
+  rest:
+    protocol: http                                                 <1>
+    hostname: my-domain.net                                        <2>
+    port: 1234                                                     <3>
+    repositoryPath: {prod-short}-backups                           <4>
+    repositoryPasswordSecretRef: backup-encryption-password-secret <5>
+    credentialsSecretRef: rest-server-auth-secret                  <6>
+----
+
+<1> Optional property that specifies the protocol which will be used. The default value is `https` with `http` as the second allowed option.
+<2> Backup server hostname.
+<3> Optional property that specifies the port on which the backup server is running. The default value is `8000`.
+<4> Path on the backup server where the backup snapshots are stored.
+<5> Secret name containing a repository password, stored under the `repo-password` field. If the secret contains only one field, its name could be arbitrary. The password is used to encrypt and decrypt backup snapshots data.
+<6> Optional property that specifies the name of the secret with the REST server user credentials, stored in the `username` and `password` fields.
+
+
+[id="configure-awss3-server-cr"]
+== Configuring AWS S3 or API compatible server
+
+[source,yaml,subs="+attributes"]
+----
+apiVersion: org.eclipse.che/v1
+kind: CheBackupServerConfiguration
+metadata:
+  name: backup-server-configuration
+spec:
+  awss3:
+    protocol: https                                                <1>
+    hostname: my-domain.net                                        <2>
+    port: 1234                                                     <3>
+    repositoryPath: {prod-short}-backups                           <4>
+    repositoryPasswordSecretRef: backup-encryption-password-secret <5>
+    awsAccessKeySecretRef: aws-user-credentials-secret             <6>
+----
+
+<1> Optional property that specifies the protocol which will be used. The default value is `https` with `http` as the second allowed option.
+<2> Optional property that specifies the S3 hostname. The default value is `s3.amazonaws.com`.
+<3> Optional property that specifies the port on which the backup server is running.
+<4> The name of the bucket resource where the backup snapshots are stored. The bucket resource must be manually pre-created.
+<5> The name of the secret containing a repository password, stored under the `repo-password` field. If the secret contains only one field, this name can be arbitrary. The password is used to encrypt and decrypt backup snapshots data.
+<6> The name of the secret containing user credentials stored in `awsAccessKeyId` and `awsSecretAccessKey` fields.
+
+
+[id="configure-sftp-server-cr"]
+== Configuring SFTP server
+
+[source,yaml,subs="+attributes"]
+----
+apiVersion: org.eclipse.che/v1
+kind: CheBackupServerConfiguration
+metadata:
+  name: backup-server-configuration
+spec:
+  awss3:
+    username: user                                                 <1>
+    hostname: my-domain.net                                        <2>
+    port: 1234                                                     <3>
+    repositoryPath: {prod-short}-backups                           <4>
+    repositoryPasswordSecretRef: backup-encryption-password-secret <5>
+    sshKeySecretRef: ssh-key-secret                                <6>
+----
+
+<1> User name on the remote server to login with using the SSH protocol.
+<2> Remote server hostname.
+<3> Optional property that specifies the port on which an SFTP server is running. The default value is `22`.
+<4> Absolute or relative path on the server where backup snapshots are stored.
+<5> The name of the secret containing a repository password, stored in the `repo-password` field. If the secret contains only one field, this name can be arbitrary. The password is used to encrypt and decrypt backup snapshots data.
+<6> The name of the secret containing a private SSH key, stored in the `ssh-privatekey` field. This SSH key can be used to perform a login without a password on an SFTP server.
+

modules/administration-guide/partials/con_setup-backup-server.adoc

@@ -0,0 +1,34 @@
+[id="con_setup-backup-server"]
+= Setting up a backup server
+
+The following section describes the supported {prod-short} backup servers and provides information for their setup.
+
+include::partial$snip_internal-backup-server-warning.adoc[]
+
+{prod-short} uses the link:https://restic.readthedocs.io/en/latest/[`restic`] tool to: 
+
+* manage backup snapshots
+
+* push to or to pull backup data from a backup server
++
+[NOTE]
+====
+The `restic` backup tool is licensed under the link:https://opensource.org/licenses/BSD-2-Clause[BSD 2-Clause] license.
+====
+
+.The backup servers currently supported for {prod-short}:
+
+* `REST`
++
+** The `REST` server was a solution designed to co-operate with the `restic` tool.
+** See link:https://restic.readthedocs.io/en/latest/[How to set up a REST server] documentation.
+
+* `Amazon S3` and API compatible alternatives.
+** See link:https://docs.aws.amazon.com/s3/index.html[AWS S3 Simple Storage Service Documentation] or the docs of alternative services that have compatible API with AWS.
+
+* `SFTP`
+** See link:https://access.redhat.com/solutions/2399571[How to configure an SFTP server]
+
+ifeval::["{project-context}" == "che"]
+or link:https://www.manpagez.com/man/8/sftp-server/[SFTP man page].
+endif::[]

modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc

@@ -0,0 +1,41 @@
+[id="configure-{prod-cli}-to-use-backup-server"]
+= Configure {prod-cli} to use backup server
+
+The following section describes how to define environment variables for a specific backup server using the {prod-cli} tool.
+
+.Procedure
+
+. Determine xref:setup-backup-server.adoc[backup server type] and the server URL. Use the link:https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html[restic repository documentation] as the reference.
++
+The URL can be specified with the `-r` parameter or defined using the `BACKUP_REPOSITORY_URL` environment variable.
+
+. Retrieve or create a password for the backup repository.
++
+The password can be specified with the `-p` parameter or defined using the `BACKUP_REPOSITORY_PASSWORD` environment variable.
++
+[WARNING]
+====
+Backup data are encrypted with this password. The loss of the backup repository password will cause losing the data.
+====
+
+. Set the following environment variables for the chosen xref:setup-backup-server.adoc[backup server type]:
+
+* `REST`
++
+When optional authentication is turned on, export `REST_SERVER_USERNAME` and `REST_SERVER_PASSWORD` environment variables.
+
+* `AWS S3`
++
+Export `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables using the AWS user credentials.
+
+* `SFTP`
++
+For the login without a password, export the `SSH_KEY_FILE` environment variable that holds the path to a file with the corresponding SSH key or provide the `--ssh-key-file` parameter.
++
+Alternatively, use the `SSH_KEY` environment variable that holds the SSH key itself.
+
+[NOTE]
+====
+It is possible to point directly to the backup server configuration object using `--backup-server-config-name` parameter or `BACKUP_SERVER_CONFIG_NAME` environment variable.
+In such a case, all the configuration above is not needed. For more details, see xref:managing-backups-through-custom-resources.adoc[]
+====

modules/administration-guide/partials/proc_managing-backups-through-cli.adoc

@@ -0,0 +1,51 @@
+[id="managing-backups-through-cli_{context}"]
+= Managing backups through {prod-cli}
+
+
+The following section describes how to create backups of {prod-short} installation and do recovery using {prod-cli}.
+
+.Prerequisites
+
+include::partial$snip_internal-backup-server-warning.adoc[]
+
+* xref:setup-backup-server.adoc[Set up a backup server].
+
+* xref:configuring-cli-to-use-backup-server.adoc[Configure {prod-cli} to use the backup server]
+
+.Procedure
+
+ * xref:cli-create-new-backup[]
+ * xref:cli-restore-from-backup[]
+
+[id="cli-create-new-backup"]
+== Create a new backup
+
+. Create a backup and send it to the pre-configured backup server:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {prod-cli} server:backup --repository-url=__<repository-url>__  --repository-password=__<repository-password>__
+----
+
+* It is possible to create other backups to the same backup server using the `server:backup` command with no arguments.
+* After using the`server:backup` command with no arguments for the first time installation of {prod-short}, an internal backup server is configured and used.
+
+
+[id="cli-restore-from-backup"]
+== Restore from a backup
+
+. Recover the previous state of {prod-short}:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {prod-cli} server:restore --repository-url=__<repository-url>__ --repository-password=__<repository-password>__
+----
+
+* The `server:restore` command can be run with no arguments when the backup server was ever used before.
+
+. Recover from a specific snapshot by specifying its ID:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {prod-cli} server:restore --snapshot-id=__<snapshot-id>__
+----