Migration documentation for rancher-turtles

hardys · hardys · commit 10b12e085c36 · 2026-01-16T13:52:42.000Z
Describes the updated install and migration steps for rancher-turtles in 3.5
diff --git a/asciidoc/components/turtles.adoc b/asciidoc/components/turtles.adoc
@@ -1,6 +1,6 @@
 [#components-rancher-turtles]
 = Rancher Turtles
-:revdate: 2025-04-25
+:revdate: 2025-12-15
 :page-revdate: {revdate}
 :experimental:
 
@@ -26,20 +26,24 @@ ____
 
 * Automatically import CAPI clusters into Rancher, by installing the Rancher Cluster Agent in CAPI provisioned clusters.
 * Install and configure CAPI controller dependencies via the https://cluster-api-operator.sigs.k8s.io/[CAPI Operator].
+* Manage installed CAPI provider dependencies via the `CAPIProvider` API
 
 == Rancher Turtles use in SUSE Edge
 
-The SUSE Edge stack provides a helm wrapper chart which installs Rancher Turtles with a specific configuration that enables:
+The SUSE Edge stack provides a `rancher-turtles-providers` helm chart that enables certain CAPI providers via the `CAPIProvider` API:
 
-* Core CAPI controller components
-* RKE2 Control Plane and Bootstrap provider components
-* <<components-metal3,Metal3>> infrastructure provider components
+* RKE2 Control Plane and Bootstrap provider
+* <<components-metal3,Metal3>> infrastructure provider
+* <<components-metal3,Metal3>> IPAM provider (currently not supported)
+* Fleet addon provider
 
 Only the default providers installed via the wrapper chart are supported - alternative Control Plane, Bootstrap and Infrastructure providers are not currently supported as part of the SUSE Edge stack.
 
 == Installing Rancher Turtles
 
-Rancher Turtles may be installed by following the <<quickstart-metal3,Metal3 Quickstart>> guide, or the <<atip-management-cluster,Management Cluster>> documentation.
+Since Rancher 2.13, Rancher Turtles is enabled by default when installing Rancher.
+
+Rancher Turtles Providers may be installed by following the <<quickstart-metal3,Metal3 Quickstart>> guide, or the <<atip-management-cluster,Management Cluster>> documentation.
 
 == Additional Resources
 
diff --git a/asciidoc/day2/migration.adoc b/asciidoc/day2/migration.adoc
@@ -1,6 +1,6 @@
 [#day2-migration]
 = Edge {version-edge} migration
-:revdate: 2025-09-30
+:revdate: 2026-01-13
 :page-revdate: {revdate}
 :experimental:
 
@@ -13,9 +13,9 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 :toc: preamble
-:previous-edge-version: 3.3
-:static-edge-version: 3.4.0
-:static-fleet-examples-tag: release-3.4.0
+:previous-edge-version: 3.4
+:static-edge-version: 3.5.0
+:static-fleet-examples-tag: release-3.5.0
 
 This section explains how to migrate your `management` and `downstream` clusters from `Edge {previous-edge-version}` to `Edge {static-edge-version}`.
 
@@ -62,7 +62,7 @@ This section covers the following topics:
 
 [NOTE]
 ====
-Applies only to clusters that require a <<components-metal3>> chart upgrade.
+Applies only to CAPI/Metal3 management clusters that require a <<components-metal3>> chart upgrade.
 ====
 
 The `Metal^3^` Helm chart includes the link:https://book.metal3.io/bmo/introduction.html[Bare Metal Operator (BMO)] CRDs by leveraging Helm's link:https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#method-1-let-helm-do-it-for-you[CRD] directory.
@@ -80,6 +80,85 @@ On a machine with `Helm` installed and `kubectl` configured to point to your `{c
 helm show crds oci://registry.suse.com/edge/charts/metal3 --version {version-metal3-chart} | kubectl apply -f -
 ----
 
+==== Prepare for Rancher Turtles upgrade
+
+[NOTE]
+====
+Applies only to CAPI/Metal3 management clusters that require a rancher turtles chart upgrade.
+
+You must ensure the management cluster is first updated to the latest 3.4 z-stream, which contains the necessary 0.24.3 Rancher Turtles version.
+====
+
+Starting with Rancher 2.13, Rancher Turtles is installed by default, therefore it is necessary to follow some additional migration steps as described in the https://turtles.docs.rancher.com/turtles/next/en/tutorials/migration.html[Rancher Turtles Documentation]
+
+First we remove the installed `CAPIProvider` resources:
+
+[,bash,subs="attributes"]
+----
+kubectl delete capiprovider -A --all
+----
+
+After waiting for the step above to complete, we next remove the installed rancher-turtles chart and rancher-turtles-airgap-resources (if installed),
+when installed via Edge Image Builder this requires removal of the corresponding `HelmChart` resources:
+
+[,bash,subs="attributes"]
+----
+kubectl delete -n kube-system helmchart rancher-turtles
+kubectl delete -n kube-system helmchart rancher-turtles-airgap-resources
+----
+
+Next we must patch the CRD resources as described in the https://turtles.docs.rancher.com/turtles/next/en/tutorials/migration.html[Rancher Turtles Documentation]
+
+[,bash]
+----
+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"}]'
+----
+
+Now follow the regular steps to upgrade the management cluster to `Edge {static-edge-version}`
+
+==== Rancher Turtles post-upgrade
+
+*After* follwing the steps below to upgrade to `Edge {static-edge-version}` it is necessary to install the new `rancher-turtles-providers` helm chart - this creates new `CAPIProvider` resources to replace those removed in the pre-upgrade steps above.
+
+This chart installation should be done via a `HelmChart` resource to enable future automated upgrade via the upgrade controller:
+
+[,shell,subs="attributes,specialchars"]
+----
+helm pull oci://registry.suse.com/edge/charts/rancher-turtles-providers --version {version-rancher-turtles-providers-chart}
+
+cat > turtles-providers-helmchart.yaml <<EOF
+apiVersion: helm.cattle.io/v1
+kind: HelmChart
+metadata:
+  annotations:
+    edge.suse.com/repository-url: oci://registry.suse.com/edge/charts/rancher-turtles-providers
+  name: rancher-turtles-providers
+  namespace: kube-system
+spec:
+  chartContent: $(base64 -w 0 rancher-turtles-providers-{version-rancher-turtles-providers-chart}.tgz)
+  failurePolicy: reinstall
+  createNamespace: true
+  targetNamespace: cattle-turtles-system
+  version: {version-rancher-turtles-providers-chart}
+EOF
+kubectl apply -f turtles-providers-helmchart.yaml
+----
+
+After a few minutes, output similar to the following should be observed:
+
+[,shell]
+----
+kubectl get capiprovider -A
+NAMESPACE                   NAME                 TYPE             PROVIDERNAME    INSTALLEDVERSION   PHASE
+capm3-system                metal3               infrastructure   metal3          v1.10.4            Ready
+cattle-capi-system          cluster-api          core             cluster-api     v1.10.6            Ready
+fleet-addon-system          fleet                addon            rancher-fleet   v0.12.0            Ready
+metal3-ipam-system          metal3ipam           ipam             metal3ipam      v1.10.4            Ready
+rke2-bootstrap-system       rke2-bootstrap       bootstrap        rke2            v0.21.1            Ready
+rke2-control-plane-system   rke2-control-plane   controlPlane     rke2            v0.21.1            Ready
+----
+
 [#day2-migration-mgmt-upgrade-controller]
 === Upgrade Controller
 
diff --git a/asciidoc/edge-book/versions.adoc b/asciidoc/edge-book/versions.adoc
@@ -87,7 +87,7 @@
 :version-neuvector-crd-chart: 108.0.1+up2.8.10
 :version-neuvector-dashboard-extension-chart: 2.1.5
 :version-rancher-chart: 2.13.1
-:version-rancher-turtles-chart: 304.0.6+up0.24.0
+:version-rancher-turtles-providers-chart: 305.0.4+up0.25.1
 :version-sriov-crd-chart: 305.0.4+up1.6.0
 :version-sriov-network-operator-chart: 305.0.4+up1.6.0
 :version-sriov-upstream: 1.6.0
diff --git a/asciidoc/product/atip-management-cluster.adoc b/asciidoc/product/atip-management-cluster.adoc
@@ -1,6 +1,6 @@
 [#atip-management-cluster]
 == Setting up the management cluster
-:revdate: 2025-07-31
+:revdate: 2025-12-01
 :page-revdate: {revdate}
 :experimental:
 
@@ -64,7 +64,6 @@ The following are the main steps to set up the management cluster using a declar
   - xref:mgmt-cluster-image-definition-file-airgap[Modifications in the definition file]: The `mgmt-cluster.yaml` file must be modified to include the `embeddedArtifactRegistry` section with the `images` field set to all container images to be included into the EIB output image.
   - xref:mgmt-cluster-custom-folder-airgap[Modifications in the custom folder]: The `custom` folder must be modified to include the resources needed to run the management cluster in an air-gap environment.
         ** Register script: The `custom/scripts/99-register.sh` script must be removed when you use an air-gap environment.
-  - xref:mgmt-cluster-helm-values-folder-airgap[Modifications in the helm values folder]: The `helm/values` folder must be modified to include the configuration needed to run the management cluster in an air-gap environment.
 
 . **xref:mgmt-cluster-image-creation[Image creation]**: This step covers the creation of the image using the Edge Image Builder tool (for both, connected and air-gap scenarios). Check the <<components-eib,prerequisites>> to run the Edge Image Builder tool on your system.
 
@@ -200,10 +199,10 @@ kubernetes:
         createNamespace: true
         installationNamespace: kube-system
         valuesFile: metal3.yaml
-      - name: rancher-turtles
-        version: {version-rancher-turtles-chart}
+      - name: rancher-turtles-providers
+        version: {version-rancher-turtles-providers-chart}
         repositoryName: suse-edge-charts
-        targetNamespace: rancher-turtles-system
+        targetNamespace: cattle-turtles-system
         createNamespace: true
         installationNamespace: kube-system
       - name: neuvector-crd
@@ -330,10 +329,10 @@ kubernetes:
         createNamespace: true
         installationNamespace: kube-system
         valuesFile: metal3.yaml
-      - name: rancher-turtles
-        version: {version-rancher-turtles-chart}
+      - name: rancher-turtles-providers
+        version: {version-rancher-turtles-providers-chart}
         repositoryName: suse-edge-charts
-        targetNamespace: rancher-turtles-system
+        targetNamespace: cattle-turtles-system
         createNamespace: true
         installationNamespace: kube-system
       - name: neuvector-crd
@@ -524,21 +523,6 @@ if [ $(${KUBECTL} get svc -n ${METAL3_CHART_TARGETNAMESPACE} metal3-metal3-ironi
 	EOF
 fi
 
-# If rancher is deployed
-if [ $(${KUBECTL} get pods -n ${RANCHER_CHART_TARGETNAMESPACE} -l app=rancher -o name | wc -l) -ge 1 ]; then
-  cat <<-EOF | ${KUBECTL} apply -f -
-	apiVersion: management.cattle.io/v3
-	kind: Feature
-	metadata:
-	  name: embedded-cluster-api
-	spec:
-	  value: false
-	EOF
-
-  # Disable Rancher webhooks for CAPI
-  ${KUBECTL} delete --ignore-not-found=true mutatingwebhookconfiguration.admissionregistration.k8s.io mutating-webhook-configuration
-  ${KUBECTL} delete --ignore-not-found=true validatingwebhookconfigurations.admissionregistration.k8s.io validating-webhook-configuration
-  ${KUBECTL} wait --for=delete namespace/cattle-provisioning-capi-system --timeout=300s
 fi
 
 # Clean up the lock cm
@@ -1007,7 +991,6 @@ interfaces:
 This section describes how to prepare the image for air-gap environments showing only the differences from the previous sections. The following changes to the previous section (xref:mgmt-cluster-image-preparation-connected[Image preparation for connected environments]) are required to prepare the image for air-gap environments:
 
 - The `mgmt-cluster.yaml` file must be modified to include the `embeddedArtifactRegistry` section with the `images` field set to all container images to be included into the EIB output image.
-- The `mgmt-cluster.yaml` file must be modified to include `rancher-turtles-airgap-resources` helm chart.
 - The `custom/scripts/99-register.sh` script must be removed when use an air-gap environment.
 
 [#mgmt-cluster-image-definition-file-airgap]
@@ -1022,8 +1005,6 @@ The following is an example of the `mgmt-cluster.yaml` file with the `embeddedAr
 Make sure to the listed images contain the component versions you need.
 ====
 
-The `rancher-turtles-airgap-resources` helm chart must also be added, this creates resources as described in the https://documentation.suse.com/cloudnative/cluster-api/{rancher-turtles-docs-version}/en/getting-started/air-gapped-environment.html[Rancher Turtles Airgap Documentation].  This also requires a turtles.yaml values file for the rancher-turtles chart to specify the necessary configuration.
-
 [,yaml,subs="attributes"]
 ----
 apiVersion: {version-eib-api-latest}
@@ -1073,17 +1054,10 @@ kubernetes:
         createNamespace: true
         installationNamespace: kube-system
         valuesFile: metal3.yaml
-      - name: rancher-turtles
-        version: {version-rancher-turtles-chart}
-        repositoryName: suse-edge-charts
-        targetNamespace: rancher-turtles-system
-        createNamespace: true
-        installationNamespace: kube-system
-        valuesFile: turtles.yaml
-      - name: rancher-turtles-airgap-resources
-        version: {version-rancher-turtles-chart}
+      - name: rancher-turtles-providers
+        version: {version-rancher-turtles-providers-chart}
         repositoryName: suse-edge-charts
-        targetNamespace: rancher-turtles-system
+        targetNamespace: cattle-turtles-system
         createNamespace: true
         installationNamespace: kube-system
       - name: neuvector-crd
@@ -1160,17 +1134,18 @@ embeddedArtifactRegistry:
     - name: registry.rancher.com/rancher/fleet:v0.13.1
     - name: registry.rancher.com/rancher/hardened-node-feature-discovery:v0.15.7-build20250425
     - name: registry.rancher.com/rancher/rancher-webhook:v0.8.1
-    - name: registry.rancher.com/rancher/rancher/turtles:v0.24.0
+    - name: registry.rancher.com/rancher/rancher/turtles:v0.25.0
     - name: registry.rancher.com/rancher/rancher:v2.12.1
     - name: registry.rancher.com/rancher/rancher-agent:v2.12.1
     - name: registry.rancher.com/rancher/shell:v0.5.0
     - name: registry.rancher.com/rancher/system-upgrade-controller:v0.16.0
-    - name: registry.suse.com/rancher/cluster-api-controller:v1.10.5
-    - name: registry.suse.com/rancher/cluster-api-provider-metal3:v1.10.2
-    - name: registry.suse.com/rancher/cluster-api-provider-rke2-bootstrap:v0.20.1
-    - name: registry.suse.com/rancher/cluster-api-provider-rke2-controlplane:v0.20.1
+    - name: registry.suse.com/rancher/cluster-api-controller:v1.10.6
+    - name: registry.suse.com/rancher/cluster-api-provider-metal3:v1.10.4
+    - name: registry.suse.com/rancher/ip-address-manager:v1.10.4
+    - name: registry.suse.com/rancher/cluster-api-provider-rke2-bootstrap:v0.21.1
+    - name: registry.suse.com/rancher/cluster-api-provider-rke2-controlplane:v0.21.1
+    - name: registry.suse.com/rancher/cluster-api-addon-provider-fleet:v0.12.0
     - name: registry.suse.com/rancher/hardened-sriov-network-operator:v1.5.0-build20250425
-    - name: registry.suse.com/rancher/ip-address-manager:v1.10.2
     - name: registry.rancher.com/rancher/kubectl:v1.32.2
     - name: registry.rancher.com/rancher/mirrored-cluster-api-controller:v1.9.5
 ----
@@ -1181,38 +1156,6 @@ embeddedArtifactRegistry:
 - The `custom/scripts/99-register.sh` script must be removed when using an air-gap environment. As you can see in the directory structure, the `99-register.sh` script is not included in the `custom/scripts` folder.
 
 
-[#mgmt-cluster-helm-values-folder-airgap]
-==== Modifications in the helm values folder
-
-- The `turtles.yaml`: contains the configuration required to specify airgapped operation for Rancher Turtles, note this depends on installation of the rancher-turtles-airgap-resources chart.
-+
-[,yaml]
-----
-cluster-api-operator:
-  cluster-api:
-    core:
-      fetchConfig:
-        selector: "{\"matchLabels\": {\"provider-components\": \"core\"}}"
-    rke2:
-      bootstrap:
-        fetchConfig:
-          selector: "{\"matchLabels\": {\"provider-components\": \"rke2-bootstrap\"}}"
-      controlPlane:
-        fetchConfig:
-          selector: "{\"matchLabels\": {\"provider-components\": \"rke2-control-plane\"}}"
-    metal3:
-      infrastructure:
-        fetchConfig:
-          selector: "{\"matchLabels\": {\"provider-components\": \"metal3\"}}"
-      ipam:
-        fetchConfig:
-          selector: "{\"matchLabels\": {\"provider-components\": \"metal3ipam\"}}"
-    fleet:
-      addon:
-        fetchConfig:
-          selector: "{\"matchLabels\": {\"provider-components\": \"fleet\"}}"
-----
-
 [#mgmt-cluster-image-creation]
 === Image creation
 
diff --git a/asciidoc/quickstart/metal3.adoc b/asciidoc/quickstart/metal3.adoc
@@ -1,6 +1,6 @@
 [#quickstart-metal3]
 = BMC automated deployments with Metal^3^
-:revdate: 2025-07-29
+:revdate: 2025-12-15
 :page-revdate: {revdate}
 :experimental:
 
@@ -64,7 +64,7 @@ The basic steps to install a management cluster and use Metal^3^ are:
 . Install Rancher
 . Install a storage provider (optional)
 . Install the Metal^3^ dependencies
-. Install CAPI dependencies via Rancher Turtles
+. Install CAPI provider dependencies
 . Build a SLEMicro OS image for downstream cluster hosts
 . Register BareMetalHost CRs to define the bare-metal inventory
 . Create a downstream cluster by defining CAPI resources
@@ -154,29 +154,19 @@ metal3-metal3-mariadb-7c7d6fdbd8-64c7l                  1/1     Running   0
 
 WARNING: Do not proceed to the following steps until all pods in the `metal3-system` namespace are running.
 
-=== Installing cluster API dependencies
+=== Installing cluster API provider dependencies
 
-Cluster API dependencies are managed via the Rancher Turtles Helm chart:
+Cluster API provider dependencies are managed via the Rancher Turtles Providers Helm chart:
 
 [,bash,subs="attributes,specialchars"]
 ----
-cat > values.yaml <<EOF
-rancherTurtles:
-  features:
-    embedded-capi:
-      disabled: true
-    rancher-webhook:
-      cleanup: true
-EOF
-
 helm install \
-  rancher-turtles oci://registry.suse.com/edge/charts/rancher-turtles \
-  --namespace rancher-turtles-system \
-  --create-namespace \
-  -f values.yaml
+  rancher-turtles oci://registry.suse.com/edge/charts/rancher-turtles-providers \
+  --namespace cattle-turtles-system \
+  --create-namespace
 ----
 
-After some time, the controller pods should be running in the `capi-system`, `capm3-system`, `rke2-bootstrap-system` and `rke2-control-plane-system` namespaces.
+After some time, the controller pods should be running in the `cattle-capi-system`, `capm3-system`, `rke2-bootstrap-system` and `rke2-control-plane-system` namespaces.
 
 === Prepare downstream cluster image
 
diff --git a/asciidoc/troubleshooting/troubleshooting-directed-network-provisioning.adoc b/asciidoc/troubleshooting/troubleshooting-directed-network-provisioning.adoc
