public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-05-21 20:35:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Jiaqi Luo
2023-10-18 10:15:07 -07:00
committed by GitHub
parent f79994a08d
commit 8f33e627b7
4 changed files with 112 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md
+43 -18
View File
@@ -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.
* `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: