public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-10 11:15:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document workaround for migrating across distributions

Browse Source 
Migrating rancher across different Kubernetes distributions causes the local
cluster object not to specify the correct distribution and driver.

This commit adds a workaround to be applied after restoration for a migration
and before bringing Rancher up, so that the local cluster will have the
correct data for the new distribution it runs on.
This commit is contained in:
Pedro Franco de Carvalho
2025-03-24 17:01:42 -03:00
parent af896b7aba
commit 58ee12d367
3 changed files with 60 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md
+20
View File
@@ -140,6 +140,26 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o
1. Once the Restore resource has the status `Completed`, you can continue the cert-manager and Rancher installation.
:::note Important:
When migrating Rancher between different Kubernetes distributions (e.g. from K3s to RKE2), the object representing the local cluster has to be modified to allow Rancher to detect the new distribution. After the restoration is completed, and **before** bringing up rancher on the new cluster, edit the local cluster object:
```bash
kubectl edit clusters.management.cattle.io local
```
1. Change the value of `status.driver` to `imported`.
1. Remove `status.provider`.
1. Remove the entire `status.version` map.
1. Remove the label with the key `provider.cattle.io` in `metadata.labels`.
1. Remove the annotation with the key `management.cattle.io/current-cluster-controllers-version` in `metadata.annotations`.
1. Remove any of `spec.rke2Config` or `spec.k3sConfig`, the entire map, if present.
1. Save the changes.
Note that removing `spec.rke2Config` or `spec.k3sConfig` will erase your distribution-specific upgrade configuration for the local cluster. It can be [reconfigured](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) if the new distribution is configurable for the local cluster.
:::
### 3. Install cert-manager
Follow the steps to [install cert-manager](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#4-install-cert-manager) in the documentation about installing cert-manager on Kubernetes.
versioned_docs/version-2.10/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md
+20
View File
@@ -140,6 +140,26 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o
1. Once the Restore resource has the status `Completed`, you can continue the cert-manager and Rancher installation.
:::note Important:
When migrating Rancher between different Kubernetes distributions (e.g. from K3s to RKE2), the object representing the local cluster has to be modified to allow Rancher to detect the new distribution. After the restoration is completed, and **before** bringing up rancher on the new cluster, edit the local cluster object:
```bash
kubectl edit clusters.management.cattle.io local
```
1. Change the value of `status.driver` to `imported`.
1. Remove `status.provider`.
1. Remove the entire `status.version` map.
1. Remove the label with the key `provider.cattle.io` in `metadata.labels`.
1. Remove the annotation with the key `management.cattle.io/current-cluster-controllers-version` in `metadata.annotations`.
1. Remove any of `spec.rke2Config` or `spec.k3sConfig`, the entire map, if present.
1. Save the changes.
Note that removing `spec.rke2Config` or `spec.k3sConfig` will erase your distribution-specific upgrade configuration for the local cluster. It can be [reconfigured](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) if the new distribution is configurable for the local cluster.
:::
### 3. Install cert-manager
Follow the steps to [install cert-manager](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#4-install-cert-manager) in the documentation about installing cert-manager on Kubernetes.
versioned_docs/version-2.11/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md
+20
View File
@@ -140,6 +140,26 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o
1. Once the Restore resource has the status `Completed`, you can continue the cert-manager and Rancher installation.
:::note Important:
When migrating Rancher between different Kubernetes distributions (e.g. from K3s to RKE2), the object representing the local cluster has to be modified to allow Rancher to detect the new distribution. After the restoration is completed, and **before** bringing up rancher on the new cluster, edit the local cluster object:
```bash
kubectl edit clusters.management.cattle.io local
```
1. Change the value of `status.driver` to `imported`.
1. Remove `status.provider`.
1. Remove the entire `status.version` map.
1. Remove the label with the key `provider.cattle.io` in `metadata.labels`.
1. Remove the annotation with the key `management.cattle.io/current-cluster-controllers-version` in `metadata.annotations`.
1. Remove any of `spec.rke2Config` or `spec.k3sConfig`, the entire map, if present.
1. Save the changes.
Note that removing `spec.rke2Config` or `spec.k3sConfig` will erase your distribution-specific upgrade configuration for the local cluster. It can be [reconfigured](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) if the new distribution is configurable for the local cluster.
:::
### 3. Install cert-manager
Follow the steps to [install cert-manager](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#4-install-cert-manager) in the documentation about installing cert-manager on Kubernetes.