diff --git a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index bb7fed4fe0a..7f3290938b4 100644 --- a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -6,29 +6,54 @@ title: Rollbacks -## Additional Steps for Rollbacks with Rancher v2.6.4+ +This page outlines how to rollback Rancher to a previous version after an upgrade. -Rancher v2.6.4 upgrades the cluster-api module from v0.4.4 to v1.0.2. Version v1.0.2 of the cluster-api, in turn, upgrades the Cluster API's Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. The CRDs upgrade to v1beta1 causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. This is because CRDs that use the older apiVersion (v1alpha4) are incompatible with v1beta1. +Follow the instructions from this page when: +- The running Rancher instance has been upgraded to a newer version after the backup was made. +- The upstream (local) cluster is the same as where the backup was made. -To avoid rollback failure, the following Rancher scripts should be run **before** you attempt a restore operation or rollback: +:::tip -* `verify.sh`: Checks for any Rancher-related resources in the cluster. -* `cleanup.sh`: Cleans up the cluster. - -See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code. - -:::caution - - There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher. +* Follow these steps to [migrate Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md). +* If you need to restore Rancher to its previous state at the same Rancher version, see the [restore documentation]( ../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md). ::: -### Rolling back from v2.6.4+ to lower versions of v2.6.x +## Alternative Steps for Special Scenarios -1. Follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts. -1. Follow these [instructions](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) to install the rancher-backup Helm chart on the existing cluster and restore the previous state. - 1. Omit Step 3. - 1. When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to. +Alternative steps need to be performed for rollbacks in the following scenarios: +- Rolling back from v2.6.4 and later to an earlier version of v2.6.x. +- Rolling back from v2.7.7 and later to an earlier version of v2.7.x. + +In Rancher v2.6.4, the cluster-api module is upgraded from v0.4.4 to v1.0.2. The cluster-api v1.0.2, in turn, upgrades the apiVersions of its Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. Custom Resources (CRs) that use the older apiVersion (v1alpha4) are incompatible with v1beta1, which causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. + +In Rancher v2.7.7, the app `rancher-provisioning-capi` is installed on the upstream (local) cluster automatically as a replacement for the embedded cluster-api controllers. Conflicts and unexpected errors will occur if the upstream cluster contains both the app, and Rancher v2.7.6 and earlier. Therefore, alternative steps are needed if you attempt to move from Rancher v2.7.7 to any previous version of Rancher v2.7.x. + +### Step 1: Clean Up the Upstream (Local) Cluster + +To avoid rollback failure, follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts **before** you attempt a restore operation or rollback: + +* `cleanup.sh`: Cleans up the cluster. +* `verify.sh`: Checks for any Rancher-related resources in the cluster. + +:::caution + +There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher. + +::: + +**Result:** all Rancher-related resources should be cleaned up on the upstream (local) cluster. + +See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code. + +### Step 2: Restore the Backup and Bring Up Rancher + +At this point, there should be no Rancher-related resources on the upstream cluster. Therefore, the next step will be the same as if you were migrating Rancher to a new cluster that contains no Rancher resources. + +Follow these [instructions](./migrate-rancher-to-new-cluster.md) to install the Rancher-Backup Helm chart and restore Rancher to its previous state. +Please keep in mind that: +1. Step 3 can be skipped, because the Cert-Manager app should still exist on the upstream (local) cluster if it was installed before. +2. At Step 4, install the Rancher version you intend to roll back to. ## Rolling Back to Rancher v2.5.0+ @@ -46,7 +71,7 @@ A restore is performed by creating a Restore custom resource. ::: -### Create the Restore Custom Resource +### Step 1: Create the Restore Custom Resource 1. Click **☰ > Cluster Management**. 1. Go to the local cluster and click **Explore**. @@ -95,7 +120,7 @@ kubectl get pods -n cattle-resources-system kubectl logs -n cattle-resources-system -f ``` -### Roll back to a previous Rancher version +### Step 2: Roll Back to a Previous Rancher Version Rancher can be rolled back using the Helm CLI. To roll back to the previous version: diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md index d78bde42e1b..f8a9ac718b8 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md @@ -8,39 +8,24 @@ title: Restoring Rancher This page outlines how to perform a restore with Rancher. -:::note Important: +Follow the instructions from this page when: +- The running Rancher instance is at the same version as when the backup was made. +- The upstream (local) cluster is the same as where the backup was made. -* Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.](migrate-rancher-to-new-cluster.md) -* While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore. -* If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation.](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md) +:::note Important + +While restoring Rancher on the same setup, the operator will scale down the Rancher deployment when restore starts, and it will scale back up the deployment once restore completes. Rancher will be unavailable during the restore. ::: -## Additional Steps for Rollbacks with Rancher v2.6.4+ +:::tip -Rancher v2.6.4 upgrades the cluster-api module from v0.4.4 to v1.0.2. Version v1.0.2 of the cluster-api, in turn, upgrades the Cluster API's Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. The CRDs upgrade to v1beta1 causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. This is because CRDs that use the older apiVersion (v1alpha4) are incompatible with v1beta1. - -To avoid rollback failure, the following Rancher scripts should be run **before** you attempt a restore operation or rollback: - -* `verify.sh`: Checks for any Rancher-related resources in the cluster. -* `cleanup.sh`: Cleans up the cluster. - -See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code. - -:::caution - - There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher. +* Follow those steps to [migrate Rancher](migrate-rancher-to-new-cluster.md). +* If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md). ::: -### Rolling back from v2.6.4+ to lower versions of v2.6.x - -1. Follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts. -1. Follow these [instructions](./migrate-rancher-to-new-cluster.md) to install the rancher-backup Helm chart on the existing cluster and restore the previous state. - 1. Omit Step 3. - 1. When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to. - -### Create the Restore Custom Resource +## Create the Restore Custom Resource A restore is performed by creating a Restore custom resource. @@ -79,7 +64,7 @@ A restore is performed by creating a Restore custom resource. 2. Cluster-scoped resources 3. Namespaced resources -### Logs +## Logs To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs: @@ -87,11 +72,11 @@ To check how the restore is progressing, you can check the logs of the operator. kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f ``` -### Cleanup +## Cleanup If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores. -### Known Issues +## Known Issues In some cases, after restoring the backup, Rancher logs will show errors similar to the following: ``` 2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing diff --git a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index bb7fed4fe0a..7f3290938b4 100644 --- a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -6,29 +6,54 @@ title: Rollbacks -## Additional Steps for Rollbacks with Rancher v2.6.4+ +This page outlines how to rollback Rancher to a previous version after an upgrade. -Rancher v2.6.4 upgrades the cluster-api module from v0.4.4 to v1.0.2. Version v1.0.2 of the cluster-api, in turn, upgrades the Cluster API's Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. The CRDs upgrade to v1beta1 causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. This is because CRDs that use the older apiVersion (v1alpha4) are incompatible with v1beta1. +Follow the instructions from this page when: +- The running Rancher instance has been upgraded to a newer version after the backup was made. +- The upstream (local) cluster is the same as where the backup was made. -To avoid rollback failure, the following Rancher scripts should be run **before** you attempt a restore operation or rollback: +:::tip -* `verify.sh`: Checks for any Rancher-related resources in the cluster. -* `cleanup.sh`: Cleans up the cluster. - -See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code. - -:::caution - - There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher. +* Follow these steps to [migrate Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md). +* If you need to restore Rancher to its previous state at the same Rancher version, see the [restore documentation]( ../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md). ::: -### Rolling back from v2.6.4+ to lower versions of v2.6.x +## Alternative Steps for Special Scenarios -1. Follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts. -1. Follow these [instructions](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) to install the rancher-backup Helm chart on the existing cluster and restore the previous state. - 1. Omit Step 3. - 1. When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to. +Alternative steps need to be performed for rollbacks in the following scenarios: +- Rolling back from v2.6.4 and later to an earlier version of v2.6.x. +- Rolling back from v2.7.7 and later to an earlier version of v2.7.x. + +In Rancher v2.6.4, the cluster-api module is upgraded from v0.4.4 to v1.0.2. The cluster-api v1.0.2, in turn, upgrades the apiVersions of its Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. Custom Resources (CRs) that use the older apiVersion (v1alpha4) are incompatible with v1beta1, which causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. + +In Rancher v2.7.7, the app `rancher-provisioning-capi` is installed on the upstream (local) cluster automatically as a replacement for the embedded cluster-api controllers. Conflicts and unexpected errors will occur if the upstream cluster contains both the app, and Rancher v2.7.6 and earlier. Therefore, alternative steps are needed if you attempt to move from Rancher v2.7.7 to any previous version of Rancher v2.7.x. + +### Step 1: Clean Up the Upstream (Local) Cluster + +To avoid rollback failure, follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts **before** you attempt a restore operation or rollback: + +* `cleanup.sh`: Cleans up the cluster. +* `verify.sh`: Checks for any Rancher-related resources in the cluster. + +:::caution + +There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher. + +::: + +**Result:** all Rancher-related resources should be cleaned up on the upstream (local) cluster. + +See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code. + +### Step 2: Restore the Backup and Bring Up Rancher + +At this point, there should be no Rancher-related resources on the upstream cluster. Therefore, the next step will be the same as if you were migrating Rancher to a new cluster that contains no Rancher resources. + +Follow these [instructions](./migrate-rancher-to-new-cluster.md) to install the Rancher-Backup Helm chart and restore Rancher to its previous state. +Please keep in mind that: +1. Step 3 can be skipped, because the Cert-Manager app should still exist on the upstream (local) cluster if it was installed before. +2. At Step 4, install the Rancher version you intend to roll back to. ## Rolling Back to Rancher v2.5.0+ @@ -46,7 +71,7 @@ A restore is performed by creating a Restore custom resource. ::: -### Create the Restore Custom Resource +### Step 1: Create the Restore Custom Resource 1. Click **☰ > Cluster Management**. 1. Go to the local cluster and click **Explore**. @@ -95,7 +120,7 @@ kubectl get pods -n cattle-resources-system kubectl logs -n cattle-resources-system -f ``` -### Roll back to a previous Rancher version +### Step 2: Roll Back to a Previous Rancher Version Rancher can be rolled back using the Helm CLI. To roll back to the previous version: diff --git a/versioned_docs/version-2.7/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md b/versioned_docs/version-2.7/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md index d78bde42e1b..f8a9ac718b8 100644 --- a/versioned_docs/version-2.7/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md +++ b/versioned_docs/version-2.7/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md @@ -8,39 +8,24 @@ title: Restoring Rancher This page outlines how to perform a restore with Rancher. -:::note Important: +Follow the instructions from this page when: +- The running Rancher instance is at the same version as when the backup was made. +- The upstream (local) cluster is the same as where the backup was made. -* Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.](migrate-rancher-to-new-cluster.md) -* While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore. -* If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation.](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md) +:::note Important + +While restoring Rancher on the same setup, the operator will scale down the Rancher deployment when restore starts, and it will scale back up the deployment once restore completes. Rancher will be unavailable during the restore. ::: -## Additional Steps for Rollbacks with Rancher v2.6.4+ +:::tip -Rancher v2.6.4 upgrades the cluster-api module from v0.4.4 to v1.0.2. Version v1.0.2 of the cluster-api, in turn, upgrades the Cluster API's Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. The CRDs upgrade to v1beta1 causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. This is because CRDs that use the older apiVersion (v1alpha4) are incompatible with v1beta1. - -To avoid rollback failure, the following Rancher scripts should be run **before** you attempt a restore operation or rollback: - -* `verify.sh`: Checks for any Rancher-related resources in the cluster. -* `cleanup.sh`: Cleans up the cluster. - -See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code. - -:::caution - - There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher. +* Follow those steps to [migrate Rancher](migrate-rancher-to-new-cluster.md). +* If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md). ::: -### Rolling back from v2.6.4+ to lower versions of v2.6.x - -1. Follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts. -1. Follow these [instructions](./migrate-rancher-to-new-cluster.md) to install the rancher-backup Helm chart on the existing cluster and restore the previous state. - 1. Omit Step 3. - 1. When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to. - -### Create the Restore Custom Resource +## Create the Restore Custom Resource A restore is performed by creating a Restore custom resource. @@ -79,7 +64,7 @@ A restore is performed by creating a Restore custom resource. 2. Cluster-scoped resources 3. Namespaced resources -### Logs +## Logs To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs: @@ -87,11 +72,11 @@ To check how the restore is progressing, you can check the logs of the operator. kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f ``` -### Cleanup +## Cleanup If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores. -### Known Issues +## Known Issues In some cases, after restoring the backup, Rancher logs will show errors similar to the following: ``` 2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing