diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 3ea9371e5b..19930e1fff 100644 --- 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 new file mode 100644 index 0000000000..8eb95ee0b5 --- /dev/null +++ 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 new file mode 100644 index 0000000000..e47705adfd --- /dev/null +++ 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 new file mode 100644 index 0000000000..39b4ba304a --- /dev/null +++ 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 new file mode 100644 index 0000000000..b6ab64fa56 --- /dev/null +++ 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 new file mode 100644 index 0000000000..23d881dcfe --- /dev/null +++ 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 index 92e51f7341..026af284c9 100644 --- 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 new file mode 100644 index 0000000000..5d0ce79818 --- /dev/null +++ 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 new file mode 100644 index 0000000000..b3605b0d16 --- /dev/null +++ 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/modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc b/modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc new file mode 100644 index 0000000000..0a1670f2ff --- /dev/null +++ b/modules/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 new file mode 100644 index 0000000000..35be19d4dc --- /dev/null +++ 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-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-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=____ +---- diff --git a/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc new file mode 100644 index 0000000000..4e4f9ad2b9 --- /dev/null +++ b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc @@ -0,0 +1,134 @@ +[id="managing-backups-using-custom-resources_{context}"] += Managing backups using custom resources + +This section describes how to create backups of {prod-short} installation and recover directly using Custom Resource objects. + +.Prerequisites + +include::partial$snip_internal-backup-server-warning.adoc[] + +* xref:setup-backup-server.adoc[Setting up a backup server]. + +* xref:define-backup-server-for-operator.adoc[Configuring {prod-cli} to use the backup server]. + +.Procedure + + * xref:operator-creating-a-new-backup[] + * xref:operator-restoring-from-a-backup[] + +[id="operator-creating-a-new-backup"] +== Creating a new backup + +. Create a `CheClusterBackup` object to create a new backup: ++ +[source,yaml,subs="+attributes"] +---- +apiVersion: org.eclipse.che/v1 +kind: CheClusterBackup +metadata: + name: {prod-short}-backup +spec: + backupServerConfigRef: backup-server-configuration <1> +---- + +<1> Name of the `CheBackupServerConfiguration` object defining what backup server to use. + +* The creation of a `CheClusterBackup` object starts a new backup. +* Before reusing the same name for a new backup object, delete the old object: ++ +[subs="+attributes,+quotes"] +---- +{orch-cli} delete CheClusterBackup __ -n {prod-namespace} +---- + +[NOTE] +==== +Editing the `CheClusterBackup` objects has no effect. +==== + +.Alternative + +To use the internal backup server, request automatic configuration from {prod-short} Operator. The preparation described above is not required. + +* Configure the automatic setup and sending of the backup to the internal backup server: ++ +[source,yaml,subs="+attributes"] +---- +apiVersion: org.eclipse.che/v1 +kind: CheClusterBackup +metadata: + name: {prod-short}-backup +spec: + useInternalBackupServer: true +---- + +[id="operator-restoring-from-a-backup"] +== Restoring from a backup + +. Create a new object of `CheClusterRestore` to recover a {prod-short} installation from a backup: ++ +[source,yaml,subs="+attributes"] +---- +apiVersion: org.eclipse.che/v1 +kind: CheClusterRestore +metadata: + name: {prod-short}-restore +spec: + backupServerConfigRef: backup-server-configuration <1> + snapshotId: ba92c7e0 <2> +---- + +<1> Name of the `CheBackupServerConfiguration` object that defines what backup server to use. +<2> Optional parameter defining the Snapshot ID to restore from. The default value is the last snapshot on the backup server. + +. Create a new `CheClusterRestore` object to request a new recovery. + +* Before reusing the same name for a new backup object, delete the old object first: ++ +[subs="+attributes,+quotes"] +---- +{orch-cli} delete CheClusterBackup __ -n {prod-namespace} +---- + +. Wait until the recovery process finishes. ++ +In a case of errors occurrences in your browser after the recovery, clean up the browser data for the {prod-short} domain. + +[NOTE] +==== +Editing of `CheClusterRestore` objects has no effect. +==== + +.Verification + +. Verify backup process state: + +.. Read the `status` section of the `CheClusterBackup` object to check the backup process: ++ +[source,yaml,subs="+attributes"] +---- +status: + message: 'Backup is in progress. Start time: ' <1> + stage: Collecting {prod-short} installation data <2> + state: InProgress <3> + snapshotId: ba92c7e0 <4> +---- +<1> Displays the overall state or error message. +<2> Current phase of the backup process in a human-readable format. +<3> Backup process state. One of `InProgress`, `Succeeded`, or `Failed`. +<4> ID of the created backup snapshot. The field appears only when `state` is `Succeeded`. + +. Verify recovery process state + +.. Read the `status` section of the `CheClusterRestore` object to check the recovery process: ++ +[source,yaml,subs="+attributes"] +---- +status: + message: 'Restore is in progress. Start time: ' <1> + stage: Restoring {prod-short} related cluster objects <2> + state: InProgress <3> +---- +<1> Overall state or error message. +<2> Current phase of the recovery process in a human-readable format. +<3> Recovery process state. One of `InProgress`, `Succeeded`, or `Failed`. diff --git a/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc new file mode 100644 index 0000000000..8f23f8bcd0 --- /dev/null +++ b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc @@ -0,0 +1,6 @@ +[NOTE] +==== +* {prod} Operator can automatically configure a backup server inside the same cluster; however, it is not recommended for production use. + +* Users who agreed to the limitations coming from the decision to back up their data inside the same {platforms-namespace} as {prod-short} installation may skip this section. +====