From 58ee12d367d8efa695bf69e9e6673e829fb2a776 Mon Sep 17 00:00:00 2001 From: Pedro Franco de Carvalho Date: Mon, 24 Mar 2025 16:30:40 -0300 Subject: [PATCH] Document workaround for migrating across distributions 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. --- .../migrate-rancher-to-new-cluster.md | 20 +++++++++++++++++++ .../migrate-rancher-to-new-cluster.md | 20 +++++++++++++++++++ .../migrate-rancher-to-new-cluster.md | 20 +++++++++++++++++++ 3 files changed, 60 insertions(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 1fe878cccfa..d065d201218 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -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. diff --git a/versioned_docs/version-2.10/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/versioned_docs/version-2.10/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 1fe878cccfa..d065d201218 100644 --- a/versioned_docs/version-2.10/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/versioned_docs/version-2.10/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -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. diff --git a/versioned_docs/version-2.11/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/versioned_docs/version-2.11/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 1fe878cccfa..d065d201218 100644 --- a/versioned_docs/version-2.11/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/versioned_docs/version-2.11/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -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.