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/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 026af284c9..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,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 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-through-cli.adoc b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc index 35be19d4dc..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,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-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 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=____ +---- + + +* 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-password=____ +$ {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. -* 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=____ +$ {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 4e4f9ad2b9..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-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"] 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/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. 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] 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