From 819667711c5db63d9edf20238971bd4bb2e974b9 Mon Sep 17 00:00:00 2001 From: Mykola Morhun Date: Thu, 30 Sep 2021 17:06:25 +0300 Subject: [PATCH 1/9] Update restore docs to include new rollback feature Signed-off-by: Mykola Morhun --- ...assembly_backup-and-disaster-recovery.adoc | 7 ++++ .../proc_managing-backups-through-cli.adoc | 35 ++++++++++++++++--- ...ging-backups-through-custom-resources.adoc | 8 ++++- 3 files changed, 44 insertions(+), 6 deletions(-) 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 026af284c9..b20ad27ac9 100644 --- a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc +++ b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc @@ -21,6 +21,13 @@ * Backup snapshots are bound to their own specific cluster and must be used only there. ==== +{prod} Operator creates a new backup on every {prod-short} update. +Depending on the xref:define-backup-server-for-operator.adoc[configuration], backups before {prod-short} update are stored in: + +* The only configured backup server +* Backup server which configuration marked with `che.eclipse.org/backup-before-update: true` annotation if there is more than one configuration +* Internal backup server if no backup servers configured or configured several and `che.eclipse.org/backup-before-update: true` annotation missing + .Additional resources diff --git a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc index 35be19d4dc..3577299659 100644 --- a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc +++ b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc @@ -34,18 +34,43 @@ $ {prod-cli} server:backup --repository-url=____ --repository-p [id="cli-restoring-from-backup"] == Restoring from a backup -. Recover the previous state of {prod-short}: +. Recover to the previous state of {prod-short}: + [source,shell,subs="+quotes,+attributes"] ---- -$ {prod-cli} server:restore --repository-url=____ --repository-password=____ +$ {prod-cli} server:restore --repository-url=____ --repository-password=____ --snapshot-id=____ ---- -* The `server:restore` command can be run with no arguments when the backup server was used before. +* It is possible to omit `--repository-url` and `--repository-password` arguments for the `server:restore` command if the same backup server should be used. -. Recover from a specific snapshot by specifying its ID: +. Recover to different than exiting version of {prod-short}: + [source,shell,subs="+quotes,+attributes"] ---- -$ {prod-cli} server:restore --snapshot-id=____ +$ {prod-cli} server:restore --version=____ --snapshot-id=____ +---- ++ +[NOTE] +==== +Provided snapshot must be created from the version of {prod-short} to which recover is requested. +==== + +* If you have a dedicated backup repository for each {prod-short} version and want to use the most recent backup for the version, +you may provide `latest` as snapshot ID and it will be converted to the latest ID in the given repository. + +. Recover to the state described by an existing backup Custom Resource object: ++ +[source,shell,subs="+quotes,+attributes"] +---- +$ {prod-cli} server:restore --backup-cr-name=____ +---- + +. Recover to the previous version after update: ++ +{prod} automatically creates a backup when upgrading to a newer version. +To return to the previous installed version run: ++ +[source,shell,subs="+quotes,+attributes"] +---- +$ {prod-cli} server:restore --rollback ---- 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 index 4e4f9ad2b9..24990b7767 100644 --- a/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc +++ b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc @@ -9,7 +9,7 @@ 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]. +* xref:define-backup-server-for-operator.adoc[Configuring {prod} to use the backup server]. .Procedure @@ -65,6 +65,12 @@ spec: [id="operator-restoring-from-a-backup"] == Restoring from a backup +[NOTE] +==== +It is impossible to recover to a different version of {prod-short} using this approach. +To do it, use `{prod-cli}` (see xref:managing-backups-using-cli.adoc#cli-restoring-from-backup[here]). +==== + . Create a new object of `CheClusterRestore` to recover a {prod-short} installation from a backup: + [source,yaml,subs="+attributes"] From 6d29ab9c96ea46a7e10930fda6337448bb6002d5 Mon Sep 17 00:00:00 2001 From: Mykola Morhun Date: Mon, 4 Oct 2021 12:34:35 +0300 Subject: [PATCH 2/9] Rephrase backup server choosing algorithm Signed-off-by: Mykola Morhun --- .../partials/assembly_backup-and-disaster-recovery.adoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) 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 b20ad27ac9..3cd0fb1094 100644 --- a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc +++ b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc @@ -22,11 +22,10 @@ ==== {prod} Operator creates a new backup on every {prod-short} update. -Depending on the xref:define-backup-server-for-operator.adoc[configuration], backups before {prod-short} update are stored in: - -* The only configured backup server -* Backup server which configuration marked with `che.eclipse.org/backup-before-update: true` annotation if there is more than one configuration -* Internal backup server if no backup servers configured or configured several and `che.eclipse.org/backup-before-update: true` annotation missing +If a backup server is xref:define-backup-server-for-operator.adoc[configured], then it is used to store the backup. +If no backup server configured, then internal backup server is used. +If there is more than one backup server configured, the server with `che.eclipse.org/backup-before-update: true` annotation is used. +If none have the annotation, then internal backup server is used. .Additional resources From fcce9445ef65eb724aa26223749d344fd602d97a Mon Sep 17 00:00:00 2001 From: Mykola Morhun Date: Mon, 4 Oct 2021 14:04:11 +0300 Subject: [PATCH 3/9] Remove last backup server context mention Signed-off-by: Mykola Morhun --- .../partials/proc_managing-backups-through-cli.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc index 3577299659..367c37eed1 100644 --- a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc +++ b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc @@ -41,8 +41,6 @@ $ {prod-cli} server:backup --repository-url=____ --repository-p $ {prod-cli} server:restore --repository-url=____ --repository-password=____ --snapshot-id=____ ---- -* It is possible to omit `--repository-url` and `--repository-password` arguments for the `server:restore` command if the same backup server should be used. - . Recover to different than exiting version of {prod-short}: + [source,shell,subs="+quotes,+attributes"] From 649bbc907d6795201826808c9470b01b3f92b6f7 Mon Sep 17 00:00:00 2001 From: Mickey Maler Date: Thu, 21 Oct 2021 11:07:39 +0200 Subject: [PATCH 4/9] Procedures: Che backup review (#2140) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * MMaler-brief-review Signed-off-by: Michal Maléř * fix Signed-off-by: Michal Maléř * vale Signed-off-by: Michal Maléř --- ...assembly_backup-and-disaster-recovery.adoc | 13 +++--- .../proc_managing-backups-through-cli.adoc | 42 ++++++++++--------- ...ging-backups-through-custom-resources.adoc | 4 +- 3 files changed, 32 insertions(+), 27 deletions(-) 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 3cd0fb1094..870c14adae 100644 --- a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc +++ b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc @@ -8,7 +8,7 @@ :context: 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: +{prod-short} 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[] @@ -21,11 +21,12 @@ * Backup snapshots are bound to their own specific cluster and must be used only there. ==== -{prod} Operator creates a new backup on every {prod-short} update. -If a backup server is xref:define-backup-server-for-operator.adoc[configured], then it is used to store the backup. -If no backup server configured, then internal backup server is used. -If there is more than one backup server configured, the server with `che.eclipse.org/backup-before-update: true` annotation is used. -If none have the annotation, then internal backup server is used. +* {prod-short} Operator creates a new backup on every {prod-short} update. +* xref:define-backup-server-for-operator.adoc[Configured] backup server is automatically used to store the backup. +* When a {prod-short} administrator configures more than one backup server, the {prod-short} Operator uses the server with the `che.eclipse.org/backup-before-update: true` annotation by default. +* {prod-short} Operator uses the internal backup server: +** Every time the {prod-short} administrator does not configure the backup server. +** When several backup servers do not have any annotation. .Additional resources diff --git a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc index 367c37eed1..4d3c723830 100644 --- a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc +++ b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc @@ -2,7 +2,7 @@ = Managing backups using {prod-cli} -The following section describes how to create backups of {prod-short} installation and do recovery 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}`. .Prerequisites @@ -20,55 +20,59 @@ include::partial$snip_internal-backup-server-warning.adoc[] [id="cli-creating-a-new-backup"] == Creating a new backup -. Create a backup and send it to the pre-configured backup server: +. 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-password=____ +$ {prod-cli} server:backup --repository-url=____ --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. -* 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 to the previous state of {prod-short}: +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}: + [source,shell,subs="+quotes,+attributes"] ---- $ {prod-cli} server:restore --repository-url=____ --repository-password=____ --snapshot-id=____ ---- -. Recover to different than exiting version of {prod-short}: + +* To roll back to a version different from the current version of {prod-short}: + [source,shell,subs="+quotes,+attributes"] ---- -$ {prod-cli} server:restore --version=____ --snapshot-id=____ +$ {prod-cli} server:restore --version=____ --snapshot-id=____ --repository-url=____ --repository-password=____ ---- + -[NOTE] -==== -Provided snapshot must be created from the version of {prod-short} to which recover is requested. -==== +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. -* If you have a dedicated backup repository for each {prod-short} version and want to use the most recent backup for the version, -you may provide `latest` as snapshot ID and it will be converted to the latest ID in the given repository. -. Recover to the state described by an existing backup Custom Resource object: +* To restore a state described by an existing backup Custom Resource: + [source,shell,subs="+quotes,+attributes"] ---- $ {prod-cli} server:restore --backup-cr-name=____ ---- -. Recover to the previous version after update: -+ -{prod} automatically creates a backup when upgrading to a newer version. -To return to the previous installed version run: + +* To roll back a version upgrade of {prod-short}: + [source,shell,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. + 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 index 24990b7767..2087303783 100644 --- a/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc +++ b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc @@ -67,10 +67,10 @@ spec: [NOTE] ==== -It is impossible to recover to a different version of {prod-short} using this approach. -To do it, use `{prod-cli}` (see xref:managing-backups-using-cli.adoc#cli-restoring-from-backup[here]). +The approach described in this chapter can not be used to recover to a different version of {prod-short}. To recover {prod-short} to another version, use the `{prod-cli}` tool. See the xref:managing-backups-using-cli.adoc#cli-restoring-from-backup[] chapter for more information. ==== + . Create a new object of `CheClusterRestore` to recover a {prod-short} installation from a backup: + [source,yaml,subs="+attributes"] From eaeb8c3d0cc0f4ff4cd481dabd94fb2f326a2999 Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Thu, 21 Oct 2021 14:37:27 +0300 Subject: [PATCH 5/9] Applying https://github.com/MichalMaler/che-docs/tree/crw-1497-mmaler-review Signed-off-by: Anatolii Bazko --- modules/administration-guide/nav.adoc | 4 +- .../configuring-cli-to-use-backup-server.adoc | 7 -- .../pages/managing-backups-using-cli.adoc | 7 -- ...assembly_backup-and-disaster-recovery.adoc | 3 +- ..._configuring-cli-to-use-backup-server.adoc | 35 --------- .../proc_managing-backups-through-cli.adoc | 78 ------------------- ...ging-backups-through-custom-resources.adoc | 9 ++- .../snip_internal-backup-server-warning.adoc | 5 +- ...using-minishift-to-set-up-openshift-3.adoc | 2 +- 9 files changed, 10 insertions(+), 140 deletions(-) delete mode 100644 modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc delete mode 100644 modules/administration-guide/pages/managing-backups-using-cli.adoc delete mode 100644 modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc delete mode 100644 modules/administration-guide/partials/proc_managing-backups-through-cli.adoc diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index a4aeb35a60..e3a07d7cf8 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -25,8 +25,8 @@ * xref:backup-and-disaster-recovery.adoc[] ** xref:setup-backup-server.adoc[] -** xref:managing-backups-using-cli.adoc[] -*** xref:configuring-cli-to-use-backup-server.adoc[] +** xref:managing-backups-using-chectl.adoc[] +*** xref:configuring-chectl-to-use-backup-server.adoc[] ** xref:managing-backups-using-custom-resources.adoc[] *** xref:define-backup-server-for-operator.adoc[] ** xref:persistent-volumes-backups.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 deleted file mode 100644 index 8eb95ee0b5..0000000000 --- a/modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[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/managing-backups-using-cli.adoc b/modules/administration-guide/pages/managing-backups-using-cli.adoc deleted file mode 100644 index 39b4ba304a..0000000000 --- a/modules/administration-guide/pages/managing-backups-using-cli.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[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/partials/assembly_backup-and-disaster-recovery.adoc b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc index 870c14adae..7b18a128fb 100644 --- a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc +++ b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc @@ -1,5 +1,4 @@ - :parent-context-of-backup-and-disaster-recovery: {context} [id="backup-and-disaster-recovery_{context}"] @@ -10,7 +9,7 @@ {prod-short} 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-chectl.adoc[] * xref:managing-backups-using-custom-resources.adoc[] 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 deleted file mode 100644 index 0a1670f2ff..0000000000 --- a/modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[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 deleted file mode 100644 index 4d3c723830..0000000000 --- a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc +++ /dev/null @@ -1,78 +0,0 @@ -[id="managing-backups-using-{prod-cli}"] -= 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}`. - -.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 - -. 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-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="cli-restoring-from-backup"] -== Restoring 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}: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {prod-cli} server:restore --repository-url=____ --repository-password=____ --snapshot-id=____ ----- - - -* To roll back to a version different from the current version of {prod-short}: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {prod-cli} server:restore --version=____ --snapshot-id=____ --repository-url=____ --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: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {prod-cli} server:restore --backup-cr-name=____ ----- - - -* To roll back a version upgrade of {prod-short}: -+ -[source,shell,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. - 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 index 2087303783..d080c7411c 100644 --- a/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc +++ b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc @@ -1,12 +1,12 @@ [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 +The following section describes how to create backups of {prod-short} installation and recover directly using Custom Resource objects. include::partial$snip_internal-backup-server-warning.adoc[] +.Prerequisites + * xref:setup-backup-server.adoc[Setting up a backup server]. * xref:define-backup-server-for-operator.adoc[Configuring {prod} to use the backup server]. @@ -14,6 +14,7 @@ include::partial$snip_internal-backup-server-warning.adoc[] .Procedure * xref:operator-creating-a-new-backup[] + * xref:operator-restoring-from-a-backup[] [id="operator-creating-a-new-backup"] @@ -67,7 +68,7 @@ spec: [NOTE] ==== -The approach described in this chapter can not be used to recover to a different version of {prod-short}. To recover {prod-short} to another version, use the `{prod-cli}` tool. See the xref:managing-backups-using-cli.adoc#cli-restoring-from-backup[] chapter for more information. +The approach described in this chapter can not be used to recover to a different version of {prod-short}. To recover {prod-short} to another version, use the `{prod-cli}` tool. See the xref:managing-backups-using-chectl[] chapter for more information. ==== diff --git a/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc index 8f23f8bcd0..2482d4c89e 100644 --- a/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc +++ b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc @@ -1,6 +1,3 @@ -[NOTE] -==== -* {prod} Operator can automatically configure a backup server inside the same cluster; however, it is not recommended for production use. +* {prod-short} 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. -==== diff --git a/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc b/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc index 72f6a0e797..1b22beab3a 100644 --- a/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc +++ b/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc @@ -9,7 +9,7 @@ This section describes how to use Minishift to configure OpenShift 3. .Prerequisites -* The `minishift` tool is available, with version `1.34.1` or greater. See link:https://docs.okd.io/3.11/minishift/getting-started/installing.html[Installing Minishift]. +* The `minishift` tool is available, with version `1.34.1` or greater. See link:https://docs.okd.io/latest/minishift/getting-started/installing.html[Installing Minishift]. * The `oc` tool is available. See link:https://docs.okd.io/latest/minishift/command-ref/minishift_oc-env.html[Setting the path of the `oc` tool]. .Procedure From 5120ab9a373016c1fe50a2bc57ffecf6c8a507ee Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Thu, 21 Oct 2021 15:02:31 +0300 Subject: [PATCH 6/9] Revert "Applying https://github.com/MichalMaler/che-docs/tree/crw-1497-mmaler-review" This reverts commit eaeb8c3d0cc0f4ff4cd481dabd94fb2f326a2999. --- modules/administration-guide/nav.adoc | 4 +- .../configuring-cli-to-use-backup-server.adoc | 7 ++ .../pages/managing-backups-using-cli.adoc | 7 ++ ...assembly_backup-and-disaster-recovery.adoc | 3 +- ..._configuring-cli-to-use-backup-server.adoc | 35 +++++++++ .../proc_managing-backups-through-cli.adoc | 78 +++++++++++++++++++ ...ging-backups-through-custom-resources.adoc | 9 +-- .../snip_internal-backup-server-warning.adoc | 5 +- ...using-minishift-to-set-up-openshift-3.adoc | 2 +- 9 files changed, 140 insertions(+), 10 deletions(-) create mode 100644 modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc create mode 100644 modules/administration-guide/pages/managing-backups-using-cli.adoc create mode 100644 modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc create mode 100644 modules/administration-guide/partials/proc_managing-backups-through-cli.adoc diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index e3a07d7cf8..a4aeb35a60 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -25,8 +25,8 @@ * xref:backup-and-disaster-recovery.adoc[] ** xref:setup-backup-server.adoc[] -** xref:managing-backups-using-chectl.adoc[] -*** xref:configuring-chectl-to-use-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[] 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/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/partials/assembly_backup-and-disaster-recovery.adoc b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc index 7b18a128fb..870c14adae 100644 --- a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc +++ b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc @@ -1,4 +1,5 @@ + :parent-context-of-backup-and-disaster-recovery: {context} [id="backup-and-disaster-recovery_{context}"] @@ -9,7 +10,7 @@ {prod-short} 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-chectl.adoc[] +* xref:managing-backups-using-cli.adoc[] * xref:managing-backups-using-custom-resources.adoc[] 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..4d3c723830 --- /dev/null +++ b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc @@ -0,0 +1,78 @@ +[id="managing-backups-using-{prod-cli}"] += 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}`. + +.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 + +. 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-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="cli-restoring-from-backup"] +== Restoring 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}: ++ +[source,shell,subs="+quotes,+attributes"] +---- +$ {prod-cli} server:restore --repository-url=____ --repository-password=____ --snapshot-id=____ +---- + + +* To roll back to a version different from the current version of {prod-short}: ++ +[source,shell,subs="+quotes,+attributes"] +---- +$ {prod-cli} server:restore --version=____ --snapshot-id=____ --repository-url=____ --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: ++ +[source,shell,subs="+quotes,+attributes"] +---- +$ {prod-cli} server:restore --backup-cr-name=____ +---- + + +* To roll back a version upgrade of {prod-short}: ++ +[source,shell,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. + 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 index d080c7411c..2087303783 100644 --- a/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc +++ b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc @@ -1,12 +1,12 @@ [id="managing-backups-using-custom-resources_{context}"] = Managing backups using custom resources -The following section describes how to create backups of {prod-short} installation and recover directly using Custom Resource objects. - -include::partial$snip_internal-backup-server-warning.adoc[] +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} to use the backup server]. @@ -14,7 +14,6 @@ include::partial$snip_internal-backup-server-warning.adoc[] .Procedure * xref:operator-creating-a-new-backup[] - * xref:operator-restoring-from-a-backup[] [id="operator-creating-a-new-backup"] @@ -68,7 +67,7 @@ spec: [NOTE] ==== -The approach described in this chapter can not be used to recover to a different version of {prod-short}. To recover {prod-short} to another version, use the `{prod-cli}` tool. See the xref:managing-backups-using-chectl[] chapter for more information. +The approach described in this chapter can not be used to recover to a different version of {prod-short}. To recover {prod-short} to another version, use the `{prod-cli}` tool. See the xref:managing-backups-using-cli.adoc#cli-restoring-from-backup[] chapter for more information. ==== diff --git a/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc index 2482d4c89e..8f23f8bcd0 100644 --- a/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc +++ b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc @@ -1,3 +1,6 @@ -* {prod-short} Operator can automatically configure a backup server inside the same cluster; however, it is not recommended for production use. +[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. +==== diff --git a/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc b/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc index 1b22beab3a..72f6a0e797 100644 --- a/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc +++ b/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc @@ -9,7 +9,7 @@ This section describes how to use Minishift to configure OpenShift 3. .Prerequisites -* The `minishift` tool is available, with version `1.34.1` or greater. See link:https://docs.okd.io/latest/minishift/getting-started/installing.html[Installing Minishift]. +* The `minishift` tool is available, with version `1.34.1` or greater. See link:https://docs.okd.io/3.11/minishift/getting-started/installing.html[Installing Minishift]. * The `oc` tool is available. See link:https://docs.okd.io/latest/minishift/command-ref/minishift_oc-env.html[Setting the path of the `oc` tool]. .Procedure From 50316430619d1a55cda5c6e24b8afe59a38f96e1 Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Thu, 21 Oct 2021 15:03:02 +0300 Subject: [PATCH 7/9] Reverting .. Signed-off-by: Anatolii Bazko --- ...nfiguring-chectl-to-use-backup-server.adoc | 7 ++ .../pages/managing-backups-using-chectl.adoc | 7 ++ ...nfiguring-chectl-to-use-backup-server.adoc | 35 +++++++++ .../proc_managing-backups-using-chectl.adoc | 77 +++++++++++++++++++ 4 files changed, 126 insertions(+) create mode 100644 modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc create mode 100644 modules/administration-guide/pages/managing-backups-using-chectl.adoc create mode 100644 modules/administration-guide/partials/proc_configuring-chectl-to-use-backup-server.adoc create mode 100644 modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc diff --git a/modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc b/modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc new file mode 100644 index 0000000000..342f0ddc52 --- /dev/null +++ b/modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc @@ -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[] diff --git a/modules/administration-guide/pages/managing-backups-using-chectl.adoc b/modules/administration-guide/pages/managing-backups-using-chectl.adoc new file mode 100644 index 0000000000..1085a4f1b9 --- /dev/null +++ b/modules/administration-guide/pages/managing-backups-using-chectl.adoc @@ -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[] diff --git a/modules/administration-guide/partials/proc_configuring-chectl-to-use-backup-server.adoc b/modules/administration-guide/partials/proc_configuring-chectl-to-use-backup-server.adoc new file mode 100644 index 0000000000..0a1670f2ff --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-chectl-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-using-chectl.adoc b/modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc new file mode 100644 index 0000000000..4cb42f9a9e --- /dev/null +++ b/modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc @@ -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-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-password=____ --snapshot-id=____ +---- + + +* To roll back to a version different from the current version of {prod-short}: ++ +[subs="+quotes,+attributes"] +---- +$ {prod-cli} server:restore --version=____ --snapshot-id=____ --repository-url=____ --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=____ +---- + + +* 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. From c02c25c1931720cd69df8a5d7f7592b6e1183b6f Mon Sep 17 00:00:00 2001 From: Mickey Maler Date: Thu, 21 Oct 2021 15:45:54 +0200 Subject: [PATCH 8/9] review (#2133) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * review Signed-off-by: Michal Maléř * sync Signed-off-by: Michal Maléř * xref fix Signed-off-by: Michal Maléř * renaming Signed-off-by: Michal Maléř * renaming Signed-off-by: Michal Maléř * fixes Signed-off-by: Michal Maléř * xref Signed-off-by: Michal Maléř * fix Signed-off-by: Michal Maléř * html test failures fix Signed-off-by: Michal Maléř * fixes Signed-off-by: Michal Maléř * vale Signed-off-by: Michal Maléř --- .../pages/managing-backups-using-chectl.adoc | 7 ++ ...assembly_backup-and-disaster-recovery.adoc | 1 - ...ging-backups-through-custom-resources.adoc | 13 ++-- .../proc_managing-backups-using-chectl.adoc | 77 +++++++++++++++++++ ...using-minishift-to-set-up-openshift-3.adoc | 2 +- 5 files changed, 92 insertions(+), 8 deletions(-) create mode 100644 modules/administration-guide/pages/managing-backups-using-chectl.adoc create mode 100644 modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc diff --git a/modules/administration-guide/pages/managing-backups-using-chectl.adoc b/modules/administration-guide/pages/managing-backups-using-chectl.adoc new file mode 100644 index 0000000000..1085a4f1b9 --- /dev/null +++ b/modules/administration-guide/pages/managing-backups-using-chectl.adoc @@ -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[] 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 870c14adae..f9b488b100 100644 --- a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc +++ b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc @@ -7,7 +7,6 @@ :context: backup-and-disaster-recovery - {prod-short} 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[] 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 index 2087303783..5836d952f6 100644 --- a/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc +++ b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc @@ -1,19 +1,21 @@ [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. +The following 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]. +.Prerequisites + +* xref:setup-backup-server.adoc[Setting up a backup server] -* xref:define-backup-server-for-operator.adoc[Configuring {prod} to use the backup server]. +* xref:define-backup-server-for-operator.adoc[Configuring {prod} to use the backup server] .Procedure * xref:operator-creating-a-new-backup[] + * xref:operator-restoring-from-a-backup[] [id="operator-creating-a-new-backup"] @@ -67,10 +69,9 @@ spec: [NOTE] ==== -The approach described in this chapter can not be used to recover to a different version of {prod-short}. To recover {prod-short} to another version, use the `{prod-cli}` tool. See the xref:managing-backups-using-cli.adoc#cli-restoring-from-backup[] chapter for more information. +The approach described in this chapter can not be used to recover to a different version of {prod-short}. To recover {prod-short} to another version, use the `{prod-cli}` tool. See the xref:managing-backups-using-chectl.adoc[] chapter for more information. ==== - . Create a new object of `CheClusterRestore` to recover a {prod-short} installation from a backup: + [source,yaml,subs="+attributes"] diff --git a/modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc b/modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc new file mode 100644 index 0000000000..2662534d75 --- /dev/null +++ b/modules/administration-guide/partials/proc_managing-backups-using-chectl.adoc @@ -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-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-password=____ --snapshot-id=____ +---- + + +* To roll back to a version different from the current version of {prod-short}: ++ +[subs="+quotes,+attributes"] +---- +$ {prod-cli} server:restore --version=____ --snapshot-id=____ --repository-url=____ --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=____ +---- + + +* 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. diff --git a/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc b/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc index 72f6a0e797..3eb812aa18 100644 --- a/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc +++ b/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc @@ -10,7 +10,7 @@ This section describes how to use Minishift to configure OpenShift 3. .Prerequisites * The `minishift` tool is available, with version `1.34.1` or greater. See link:https://docs.okd.io/3.11/minishift/getting-started/installing.html[Installing Minishift]. -* The `oc` tool is available. See link:https://docs.okd.io/latest/minishift/command-ref/minishift_oc-env.html[Setting the path of the `oc` tool]. +* The `oc` tool is available. See link:https://docs.okd.io/3.11/minishift/command-ref/minishift_oc-env.html[Setting the path of the `oc` tool]. .Procedure From 9ce72ef92990147601243898faf0ba356eeb768d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Mal=C3=A9=C5=99?= Date: Thu, 21 Oct 2021 15:58:27 +0200 Subject: [PATCH 9/9] html test fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michal Maléř --- modules/extensions/partials/assembly_eclipse-che4z.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/extensions/partials/assembly_eclipse-che4z.adoc b/modules/extensions/partials/assembly_eclipse-che4z.adoc index 9cf5f62618..85013526e1 100644 --- a/modules/extensions/partials/assembly_eclipse-che4z.adoc +++ b/modules/extensions/partials/assembly_eclipse-che4z.adoc @@ -71,7 +71,7 @@ You can learn more about the Zowe Explorer by watching the https://www.youtube.c link:https://github.com/zowe/vscode-extension-for-zowe/issues[image:https://img.shields.io/github/issues-raw/zowe/vscode-extension-for-zowe?style=flat-square[GitHub issues]] link:https://openmainframeproject.slack.com/[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[slack]] -* For documentation, see link:https://docs.zowe.org/stable/user-guide/ze-install.html[Zowe Docs] +* For documentation, see link:https://docs.zowe.org/stable/user-guide/ze-install/[Zowe Docs] * For the feedback related to the topic of improving Zowe Explorer, see link:https://github.com/zowe/vscode-extension-for-zowe/issues[Let us know on our Git repository]