Migration guide

Context

Starting with Rancher v2.13, Rancher Turtles gets installed as part of Rancher, eliminating the need for a separate deployment. Prior to upgrading to Rancher v2.13, users are required to follow this guide to ensure a smooth upgrade process.

Migration

Follow the steps below in order, before upgrading to Rancher v2.13:

  1. Ensure that you upgrade Rancher Turtles to v0.24.3. This step is important because all patch releases for v0.24 prepare the cluster for the upgrade to Rancher v2.13.

  2. Uninstall Rancher Turtles. This is necessary because from Rancher v2.13 onwards, Rancher Turtles is no longer an opt-in addon but a Rancher system component. As such, Rancher installs it in a different namespace than before and therefore the previously installed version needs to be manually uninstalled first. Uninstalling v0.24.3 of Rancher Turtles removes the core CAPI provider itself but keeps the core CAPI CRDs. During migration, the core CAPI controller will not be running on the management cluster, but any downstream CAPI clusters should continue to run as usual and not be affected.

  3. Run the following kubectl commands:

    kubectl patch crd capiproviders.turtles-capi.cattle.io --type=json -p='[{"op": "add", "path": "/metadata/annotations/meta.helm.sh~1release-namespace", "value": "cattle-turtles-system"}]'
kubectl patch crd clusterctlconfigs.turtles-capi.cattle.io --type=json -p='[{"op": "add", "path": "/metadata/annotations/meta.helm.sh~1release-namespace", "value": "cattle-turtles-system"}]'

    These commands will patch the capiprovider and clusterctlconfig CRDs so that they become adopted by Rancher Turtles when installed as part of Rancher v2.13.

Note, that the migration described above is necessary for users running Rancher Turtles versions ≤ v0.24.3. New users that are installing Rancher v2.13 do not need to perform any migration.