diff --git a/asciidoc/components/turtles.adoc b/asciidoc/components/turtles.adoc index ad7e3b0c..6d41990d 100644 --- 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 -* <> infrastructure provider components +* RKE2 Control Plane and Bootstrap provider +* <> infrastructure provider +* <> 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 <> guide, or the <> documentation. +Since Rancher 2.13, Rancher Turtles is enabled by default when installing Rancher. + +Rancher Turtles Providers may be installed by following the <> guide, or the <> documentation. == Additional Resources diff --git a/asciidoc/day2/migration.adoc b/asciidoc/day2/migration.adoc index 5194f7a4..7d37cc59 100644 --- 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 <> chart upgrade. +Applies only to CAPI/Metal3 management clusters that require a <> 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 <> 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 index e076e4f4..490b26cd 100644 --- 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 <