docs: Update restore docs to include new rollback feature

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[]

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[]

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[]

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

@@ -7,8 +7,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,6 +20,13 @@
 * Backup snapshots are bound to their own specific cluster and must be used only there.
 ====
 
+* {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
 
 

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[]
+====

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,32 +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-url>__  --repository-password=__<repository-password>__
+$ {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.
 
-* 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}:
+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-url>__ --repository-password=__<repository-password>__ --snapshot-id=__<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 --repository-url=__<repository-url>__ --repository-password=__<repository-password>__
+$ {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.
 
-* 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:
+* To restore a state described by an existing backup Custom Resource:
 +
 [source,shell,subs="+quotes,+attributes"]
 ----
-$ {prod-cli} server:restore --snapshot-id=__<snapshot-id>__
+$ {prod-cli} server:restore --backup-cr-name=__<CheClusterBackupCRName>__
 ----
+
+
+* 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.
+

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-cli} 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"]
@@ -65,6 +67,11 @@ spec:
 [id="operator-restoring-from-a-backup"]
 == Restoring from a backup
 
+[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.adoc[] chapter for more information.
+====
+
 . Create a new object of `CheClusterRestore` to recover a {prod-short} installation from a backup:
 +
 [source,yaml,subs="+attributes"]

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-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.

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-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.

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