Add Backup / Restore docs (#2072)

* Add Backup / Restore docs Signed-off-by: Mykola Morhun <[email protected]> * Che 19962 mmaler review (#2080) review after a review Signed-off-by: Michal Maléř <[email protected]> * Apply suggestions from @rkratky's code review Co-authored-by: Robert Krátký <[email protected]> * Fix links and nav Signed-off-by: Mykola Morhun <[email protected]> * Rephrase word 'passwordless' to make vale check passing Signed-off-by: Mykola Morhun <[email protected]> Co-authored-by: Michal Maléř <[email protected]> Co-authored-by: Anatolii Bazko <[email protected]> Co-authored-by: Robert Krátký <[email protected]>
eclipse-che · Aug 9, 2021 · 9efca7a · 9efca7a
1 parent 090c8e5
commit 9efca7a
Show file tree

Hide file tree

Showing 13 changed files with 411 additions and 4 deletions.
diff --git a/modules/administration-guide/nav.adoc b/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-using-cli.adoc[]
+*** xref:configuring-cli-to-use-backup-server.adoc[]
+** xref:managing-backups-using-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[]

diff --git a/modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc b/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 a 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[]
diff --git a/modules/administration-guide/pages/define-backup-server-for-operator.adoc b/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 a backup server
+:keywords: administration-guide, backup, recovery, operator
+:page-aliases: .:define-backup-server-for-operator
+
+include::partial$con_define-backup-server-for-operator.adoc[]
diff --git a/modules/administration-guide/pages/managing-backups-using-cli.adoc b/modules/administration-guide/pages/managing-backups-using-cli.adoc
@@ -0,0 +1,7 @@
+[id="managing-backups-using-cli"]
+// = Managing backups through cli
+:navtitle: Managing backups using CLI
+:keywords: administration-guide, backup, recovery
+:page-aliases: .:managing-backups-through-cli
+
+include::partial$proc_managing-backups-through-cli.adoc[]
diff --git a/modules/administration-guide/pages/managing-backups-using-custom-resources.adoc b/modules/administration-guide/pages/managing-backups-using-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[]
diff --git a/modules/administration-guide/pages/setup-backup-server.adoc b/modules/administration-guide/pages/setup-backup-server.adoc
@@ -0,0 +1,7 @@
+[id="setting-up-a-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[]
diff --git a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc b/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-using-cli.adoc[]
+* xref:managing-backups-using-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}
diff --git a/modules/administration-guide/partials/con_define-backup-server-for-operator.adoc b/modules/administration-guide/partials/con_define-backup-server-for-operator.adoc
@@ -0,0 +1,98 @@
+[id="configuring-{prod-id-short}-to-use-a-backup-server"]
+= Configuring {prod-short} to use a 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:configuring-rest-server-cr[REST]
+ * xref:configuring-aws-s3-or-api-compatible-server-cr[AWS S3 or API compatible]
+ * xref:configuring-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="configuring-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 to 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 in the `repo-password` field. If the secret contains only one field, its name is 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="configuring-aws-s3-or-api-compatible-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 to 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 in the `repo-password` field. If the secret contains only one field, this name is arbitrary. The password is used to encrypt and decrypt backup snapshots data.
+<6> The name of the secret containing user credentials stored in the `awsAccessKeyId` and `awsSecretAccessKey` fields.
+
+
+[id="configuring-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 is 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.
diff --git a/modules/administration-guide/partials/con_setup-backup-server.adoc b/modules/administration-guide/partials/con_setup-backup-server.adoc
@@ -0,0 +1,29 @@
+[id="setting-up-a-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 is a solution designed to cooperate 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::[]
+.
diff --git a/...es/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc b/...es/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc
@@ -0,0 +1,35 @@
+[id="configuring-{prod-cli}-to-use-a-backup-server"]
+= Configuring {prod-cli} to use a 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 the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables with AWS user credentials.
+
+SFTP:: For login without a password, export the `SSH_KEY_FILE` environment variable that holds the path to a file with a corresponding SSH key, or provide the `--ssh-key-file` parameter.
++
+Alternatively, the `SSH_KEY` environment variable that holds an SSH key itself can be used.
+
+[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-using-custom-resources.adoc[]
+====
diff --git a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc
@@ -0,0 +1,51 @@
+[id="managing-backups-using-{prod-cli}"]
+= Managing backups using {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-creating-a-new-backup[]
+ * xref:cli-restoring-from-backup[]
+
+[id="cli-creating-a-new-backup"]
+== Creating 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 on installation of {prod-short}, an internal backup server is configured and used.
+
+
+[id="cli-restoring-from-backup"]
+== Restoring 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 used before.
+
+. Recover from a specific snapshot by specifying its ID:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+$ {prod-cli} server:restore --snapshot-id=__<snapshot-id>__
+----