update the instructions for rancher restore and rollback (#925)

2026-09-28 14:08:55 +00:00 · 2023-10-18 10:15:07 -07:00
parent f79994a08d
commit 8f33e627b7
4 changed files with 112 additions and 92 deletions
@@ -6,29 +6,54 @@ title: Rollbacks
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks"/>
 </head>
-## 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.
+* Follow these steps to [migrate Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md).
-*  `cleanup.sh`: Cleans up the cluster.
+* 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).
 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.
 :::
-### 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.
+Alternative steps need to be performed for rollbacks in the following scenarios:
-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.
+- Rolling back from v2.6.4 and later to an earlier version of v2.6.x.
-    1. Omit Step 3.
+- Rolling back from v2.7.7 and later to an earlier version of v2.7.x.
-    1. When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to.
+
 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:
@@ -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)
+:::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. 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)
+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.
+* 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).
 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.
 :::
-### Rolling back from v2.6.4+ to lower versions of v2.6.x
+## Create the Restore Custom Resource
 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
 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
@@ -6,29 +6,54 @@ title: Rollbacks
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks"/>
 </head>
-## 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.
+* Follow these steps to [migrate Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md).
-*  `cleanup.sh`: Cleans up the cluster.
+* 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).
 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.
 :::
-### 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.
+Alternative steps need to be performed for rollbacks in the following scenarios:
-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.
+- Rolling back from v2.6.4 and later to an earlier version of v2.6.x.
-    1. Omit Step 3.
+- Rolling back from v2.7.7 and later to an earlier version of v2.7.x.
-    1. When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to.
+
 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:
@@ -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)
+:::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. 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)
+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.
+* 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).
 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.
 :::
-### Rolling back from v2.6.4+ to lower versions of v2.6.x
+## Create the Restore Custom Resource
 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
 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