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 1/6] 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. From 5e2157add80e54d115dbbbdf3c1961a3e58dbd76 Mon Sep 17 00:00:00 2001 From: Pedro Franco de Carvalho Date: Wed, 26 Mar 2025 15:10:41 -0300 Subject: [PATCH 2/6] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 d065d201218..de8ab6417d4 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 @@ -142,7 +142,7 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o :::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: +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 From 1748e5b6f330a7e94e3f15b29f31219d40b514de Mon Sep 17 00:00:00 2001 From: Pedro Franco de Carvalho Date: Wed, 26 Mar 2025 15:10:49 -0300 Subject: [PATCH 3/6] Update versioned_docs/version-2.10/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 d065d201218..de8ab6417d4 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 @@ -142,7 +142,7 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o :::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: +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 From bb190560b5b4a9a6837d1c0586163f450dde9c86 Mon Sep 17 00:00:00 2001 From: Pedro Franco de Carvalho Date: Wed, 26 Mar 2025 15:10:56 -0300 Subject: [PATCH 4/6] Update versioned_docs/version-2.11/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 d065d201218..de8ab6417d4 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 @@ -142,7 +142,7 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o :::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: +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 From 371275ee248c24ee8646ee4d3672292a4faab318 Mon Sep 17 00:00:00 2001 From: Pedro Franco de Carvalho Date: Wed, 26 Mar 2025 15:41:11 -0300 Subject: [PATCH 5/6] Emphasize workaround applies to any two distros --- .../migrate-rancher-to-new-cluster.md | 2 +- .../migrate-rancher-to-new-cluster.md | 2 +- .../migrate-rancher-to-new-cluster.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) 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 de8ab6417d4..578d57b1c87 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 @@ -142,7 +142,7 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o :::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: +When migrating Rancher between any two 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 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 de8ab6417d4..578d57b1c87 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 @@ -142,7 +142,7 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o :::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: +When migrating Rancher between any two 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 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 de8ab6417d4..578d57b1c87 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 @@ -142,7 +142,7 @@ Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-o :::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: +When migrating Rancher between any two 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 From 94ccdfbf63eda80def3921a11bd2284ad79fc456 Mon Sep 17 00:00:00 2001 From: Pedro Franco de Carvalho Date: Wed, 26 Mar 2025 15:45:49 -0300 Subject: [PATCH 6/6] Better wording --- .../migrate-rancher-to-new-cluster.md | 2 +- .../migrate-rancher-to-new-cluster.md | 2 +- .../migrate-rancher-to-new-cluster.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) 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 578d57b1c87..a9da73ae894 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 @@ -153,7 +153,7 @@ kubectl edit clusters.management.cattle.io local 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. Remove the entire `spec.rke2Config` or `spec.k3sConfig` 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. 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 578d57b1c87..a9da73ae894 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 @@ -153,7 +153,7 @@ kubectl edit clusters.management.cattle.io local 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. Remove the entire `spec.rke2Config` or `spec.k3sConfig` 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. 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 578d57b1c87..a9da73ae894 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 @@ -153,7 +153,7 @@ kubectl edit clusters.management.cattle.io local 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. Remove the entire `spec.rke2Config` or `spec.k3sConfig` 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.