From 5046e362838cf5bcdf155937b7756c45af332ff2 Mon Sep 17 00:00:00 2001 From: OdedNeuhaus Date: Mon, 11 Aug 2025 20:20:22 +0300 Subject: [PATCH] Update migrate-rancher-to-new-cluster.md I was migrating my Rancher instance to a new cluster running RKE2 (the original local cluster was running RKE1), if followed the steps as described in https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster I found out that after i made the change on my DNS server - all the clusters that were registrated to my original Rancher server - were stuck on updating in the new Rancher server. I figured out that the cattle-cluster-agents were still communicating with the old Rancher server, and had to be restarted, or fail their connection with it - in order to make them communicate with the new Rancher server. I assume that more Rancher users can experience this problem, and this add to the Rancher migration guide will make their migrating operation easier. --- .../migrate-rancher-to-new-cluster.md | 29 +++++++++++++++++++ 1 file changed, 29 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 7710976d2a6..4c8f28d3c5c 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 @@ -197,3 +197,32 @@ helm install rancher rancher-latest/rancher -n cattle-system -f rancher-values.y After migration completes, update your DNS records and any load balancers, so that traffic is routed correctly to the migrated cluster. Remember that you must use the same hostname that was set as the server URL in the original cluster. Full instructions on how to redirect traffic to the migrated cluster differ based on your specific environment. Refer to your hosting provider's documentation for more details. + +### 6. Scale down the original Rancher instance + +After redirecting traffic to the new Rancher environment, **scale the original Rancher instance to 0 replicas** so it no longer contacts with your managed clusters. + +Leaving the old server up can cause agents to keep contacting the original `server-url`, which often leaves clusters stuck in **Updating** in the new environment. + +```bash +kubectl scale deployment rancher -n cattle-system --replicas=0 +``` + +If you originally ran Rancher in Docker: + +```bash +docker stop +``` + +:::note + +If you wish to keep the original Rancher environment running, you can also restart the cattle-cluster-agent pods on each cluster connected to your Rancher environment. + +```bash +kubectl rollout restart deployment cattle-cluster-agent -n cattle-system +``` + +This triggers a rolling restart of the agent so it re-establishes the connection to the new Rancher environment. + +::: +