-
Notifications
You must be signed in to change notification settings - Fork 164
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Update restore docs to include new rollback feature (#2124)
* Update restore docs to include new rollback feature Signed-off-by: Mykola Morhun <mmorhun@redhat.com> * Rephrase backup server choosing algorithm Signed-off-by: Mykola Morhun <mmorhun@redhat.com> * Remove last backup server context mention Signed-off-by: Mykola Morhun <mmorhun@redhat.com> * Procedures: Che backup review (#2140) * MMaler-brief-review Signed-off-by: Michal Maléř <mmaler@redhat.com> * fix Signed-off-by: Michal Maléř <mmaler@redhat.com> * vale Signed-off-by: Michal Maléř <mmaler@redhat.com> * Applying https://github.com/MichalMaler/che-docs/tree/crw-1497-mmaler-review Signed-off-by: Anatolii Bazko <abazko@redhat.com> * Revert "Applying https://github.com/MichalMaler/che-docs/tree/crw-1497-mmaler-review" This reverts commit eaeb8c3. * Reverting .. Signed-off-by: Anatolii Bazko <abazko@redhat.com> * review (#2133) * review Signed-off-by: Michal Maléř <mmaler@redhat.com> * sync Signed-off-by: Michal Maléř <mmaler@redhat.com> * xref fix Signed-off-by: Michal Maléř <mmaler@redhat.com> * renaming Signed-off-by: Michal Maléř <mmaler@redhat.com> * renaming Signed-off-by: Michal Maléř <mmaler@redhat.com> * fixes Signed-off-by: Michal Maléř <mmaler@redhat.com> * xref Signed-off-by: Michal Maléř <mmaler@redhat.com> * fix Signed-off-by: Michal Maléř <mmaler@redhat.com> * html test failures fix Signed-off-by: Michal Maléř <mmaler@redhat.com> * fixes Signed-off-by: Michal Maléř <mmaler@redhat.com> * vale Signed-off-by: Michal Maléř <mmaler@redhat.com> * html test fix Signed-off-by: Michal Maléř <mmaler@redhat.com> Co-authored-by: Anatolii Bazko <abazko@redhat.com> Co-authored-by: Michal Maléř <mmaler@redhat.com>
- Loading branch information
3 people
authored
Oct 21, 2021
1 parent
824bc3f
commit 3c76f57
Showing
11 changed files
with
268 additions
and
18 deletions.
There are no files selected for viewing
7 changes: 7 additions & 0 deletions
7
modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| [id="configuring-chectl-to-use-backup-server"] | ||
| // = Configuring chectl to use a backup server | ||
| :navtitle: Configuring chectl to use a backup server | ||
| :keywords: administration-guide, backup, recovery, cli, chectl | ||
| :page-aliases: .:configure-chectl-to-use-backup-server | ||
|
|
||
| include::partial$proc_configuring-chectl-to-use-backup-server.adoc[] |
7 changes: 7 additions & 0 deletions
7
modules/administration-guide/pages/managing-backups-using-chectl.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| [id="managing-backups-using-chectl"] | ||
| // = Managing backups using chectl | ||
| :navtitle: Managing backups using chectl | ||
| :keywords: administration-guide, backup, recovery | ||
| :page-aliases: .:managing-backups-using-chectl | ||
|
|
||
| include::partial$proc_managing-backups-using-chectl.adoc[] |
7 changes: 7 additions & 0 deletions
7
modules/administration-guide/pages/managing-backups-using-chectl.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| [id="managing-backups-using-chectl"] | ||
| // = Managing backups using chectl | ||
| :navtitle: Managing backups using chectl | ||
| :keywords: administration-guide, backup, recovery | ||
| :page-aliases: .:managing-backups-using-chectl | ||
|
|
||
| include::partial$proc_managing-backups-using-chectl.adoc[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
35 changes: 35 additions & 0 deletions
35
...administration-guide/partials/proc_configuring-chectl-to-use-backup-server.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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[] | ||
| ==== |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
77 changes: 77 additions & 0 deletions
77
modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| [id="managing-backups-using-chectl_{context}"] | ||
| = Managing backups using {prod-cli} | ||
|
|
||
| The following section describes how to create and use backups of a {prod-short} installation to perform a recovery or a rollback to a previous version using `{prod-cli}`. | ||
|
|
||
| include::partial$snip_internal-backup-server-warning.adoc[] | ||
|
|
||
| .Prerequisites | ||
|
|
||
| * xref:setup-backup-server.adoc[Set up a backup server]. | ||
|
|
||
| * xref:configuring-chectl-to-use-backup-server.adoc[Configure {prod-cli} to use the backup server]. | ||
|
|
||
| .Procedure | ||
|
|
||
| * xref:creating-a-new-backup-using-{prod-cli}_{context}[] | ||
|
|
||
| * xref:restoring-from-a-backup-using-{prod-cli}_{context}[] | ||
|
|
||
|
|
||
| [id="creating-a-new-backup-using-{prod-cli}_{context}"] | ||
| == Creating a {prod-short} backup | ||
|
|
||
| . To create a backup snapshot and send it to a pre-configured backup server: | ||
| + | ||
| [source,shell,subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:backup --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ | ||
| ---- | ||
| + | ||
| * You can create other backups to the same backup server using the `server:backup` command with no arguments. | ||
| * Using the `server:backup` command with no arguments for the first time will configure and use an internal backup server. | ||
|
|
||
|
|
||
| [id="restoring-from-a-backup-using-{prod-cli}_{context}"] | ||
| == Restoring {prod-short} from a backup | ||
|
|
||
| A {prod-short} administrator can use an existing snapshot of a particular {prod-short} version to restore a desired state or version. The following instructions describe several variations of the restoration command. Adjust the command arguments according to your use case. | ||
|
|
||
| * To restore the previous functional state of the same version of {prod-short}: | ||
| + | ||
| [subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:restore --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ --snapshot-id=__<snapshot-id>__ | ||
| ---- | ||
|
|
||
|
|
||
| * To roll back to a version different from the current version of {prod-short}: | ||
| + | ||
| [subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:restore --version=__<version>__ --snapshot-id=__<snapshot-id>__ --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ | ||
| ---- | ||
| + | ||
| This performs a version rollback and restores a snapshot made from a previous version of {prod-short}. The provided snapshot must be created from the version of {prod-short} to which you want to roll back. | ||
| + | ||
| NOTE: If you have a dedicated backup repository for each {prod-short} version and want to use the most recent backup for the version, you can provide the `latest` argument as a snapshot ID. By doing so, the `latest` argument will be converted to the latest known ID in the given repository, which will be then used by the {prod-short} Operator to recover. | ||
|
|
||
|
|
||
| * To restore a state described by an existing backup Custom Resource: | ||
| + | ||
| [subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:restore --backup-cr-name=__<CheClusterBackupCRName>__ | ||
| ---- | ||
|
|
||
|
|
||
| * To roll back a version upgrade of {prod-short}: | ||
| + | ||
| [subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:restore --rollback | ||
| ---- | ||
| + | ||
| This recovers the version that {prod-short} was using before upgrading to a later version. | ||
| + | ||
| NOTE: {prod-short} Operator automatically creates a backup before every upgrade. |
77 changes: 77 additions & 0 deletions
77
modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| [id="managing-backups-using-chectl_{context}"] | ||
| = Managing backups using {prod-cli} | ||
|
|
||
| The following section describes how to create and use backups of a {prod-short} installation to perform a recovery or a rollback to a previous version using `{prod-cli}`. | ||
|
|
||
| include::partial$snip_internal-backup-server-warning.adoc[] | ||
|
|
||
| .Prerequisites | ||
|
|
||
| * xref:setup-backup-server.adoc[Set up a backup server]. | ||
|
|
||
| * xref:configuring-chectl-to-use-backup-server.adoc[Configure {prod-cli} to use the backup server]. | ||
|
|
||
| .Procedure | ||
|
|
||
| * xref:creating-a-new-backup-using-{prod-cli}_{context}[] | ||
|
|
||
| * xref:restoring-from-a-backup-using-{prod-cli}_{context}[] | ||
|
|
||
|
|
||
| [id="creating-a-new-backup-using-{prod-cli}_{context}"] | ||
| == Creating a {prod-short} backup | ||
|
|
||
| . To create a backup snapshot and send it to a pre-configured backup server: | ||
| + | ||
| [source,shell,subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:backup --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ | ||
| ---- | ||
| + | ||
| * You can create other backups to the same backup server using the `server:backup` command with no arguments. | ||
| * Using the `server:backup` command with no arguments for the first time will configure and use an internal backup server. | ||
|
|
||
|
|
||
| [id="restoring-from-a-backup-using-{prod-cli}_{context}"] | ||
| == Restoring {prod-short} from a backup | ||
|
|
||
| A {prod-short} admin can use an existing snapshot of a particular {prod-short} version to restore a desired state or version. The following instructions describe several variations of the restoration command. Adjust the command arguments according to your use case. | ||
|
|
||
| * To restore the previous functional state of the same version of {prod-short}: | ||
| + | ||
| [subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:restore --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ --snapshot-id=__<snapshot-id>__ | ||
| ---- | ||
|
|
||
|
|
||
| * To roll back to a version different from the current version of {prod-short}: | ||
| + | ||
| [subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:restore --version=__<version>__ --snapshot-id=__<snapshot-id>__ --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ | ||
| ---- | ||
| + | ||
| This performs a version rollback and restores a snapshot made from a previous version of {prod-short}. The provided snapshot must be created from the version of {prod-short} to which you want to roll back. | ||
| + | ||
| NOTE: If you have a dedicated backup repository for each {prod-short} version and want to use the most recent backup for the version, you can provide the `latest` argument as a snapshot ID. By doing so, the `latest` argument will be converted to the latest known ID in the given repository, which will be then used by the {prod-short} Operator to recover. | ||
|
|
||
|
|
||
| * To restore a state described by an existing backup Custom Resource: | ||
| + | ||
| [subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:restore --backup-cr-name=__<CheClusterBackupCRName>__ | ||
| ---- | ||
|
|
||
|
|
||
| * To roll back a version upgrade of {prod-short}: | ||
| + | ||
| [subs="+quotes,+attributes"] | ||
| ---- | ||
| $ {prod-cli} server:restore --rollback | ||
| ---- | ||
| + | ||
| This recovers the version that {prod-short} was using before upgrading to a later version. | ||
| + | ||
| NOTE: {prod-short} Operator automatically creates a backup before every upgrade. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters