ClusterClass

In this section we cover using ClusterClass with Rancher Turtles.

Prerequisites

Rancher Manager cluster with Rancher Turtles installed

Setup

Azure

To prepare the management Cluster, we are going to install the Cluster API Provider Azure, and create a ServicePrincipal identity to provision a new Cluster on Azure.
Before we start, a ServicePrincipal needs to be created, with at least Contributor access to an Azure subscription.
Refer to the CAPZ documentation for more details.

Provider installation

apiVersion: v1
kind: Namespace
metadata:
  name: capz-system
---
apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
  name: azure
  namespace: capz-system
spec:
  type: infrastructure
  name: azure

Identity setup

A Secret containing the ADD Service Principal password need to be created first.

# Settings needed for AzureClusterIdentity used by the AzureCluster
export AZURE_CLUSTER_IDENTITY_SECRET_NAME="cluster-identity-secret"
export AZURE_CLUSTER_IDENTITY_SECRET_NAMESPACE="default"
export AZURE_CLIENT_SECRET="<Password>"

# Create a secret to include the password of the Service Principal identity created in Azure
# This secret will be referenced by the AzureClusterIdentity used by the AzureCluster
kubectl create secret generic "${AZURE_CLUSTER_IDENTITY_SECRET_NAME}" --from-literal=clientSecret="${AZURE_CLIENT_SECRET}" --namespace "${AZURE_CLUSTER_IDENTITY_SECRET_NAMESPACE}"

The AzureClusterIdentity can now be created to use the Service Principal identity.
Note that the AzureClusterIdentity is a namespaced resource and it needs to be created in the same namespace as the Cluster.
For more information on best practices when using Azure identities, please refer to the official documentation.

Note that some variables are left to the user to substitute.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: AzureClusterIdentity
metadata:
  labels:
    clusterctl.cluster.x-k8s.io/move-hierarchy: "true"
  name: cluster-identity
spec:
  allowedNamespaces: {}
  clientID: <AZURE_APP_ID>
  clientSecret:
    name: <AZURE_CLUSTER_IDENTITY_SECRET_NAME>
    namespace: <AZURE_CLUSTER_IDENTITY_SECRET_NAMESPACE>
  tenantID: <AZURE_TENANT_ID>
  type: ServicePrincipal

Create a Cluster from a ClusterClass

Examples using HelmApps need at least Rancher v2.11, or otherwise Fleet v0.12 or higher.

Azure RKE2
Azure AKS

An Azure ClusterClass can be found among the Turtles examples.

kubectl apply -f https://raw.githubusercontent.com/rancher/turtles/refs/heads/main/examples/clusterclasses/azure/clusterclass-rke2-example.yaml

Additionally, the Azure Cloud Provider will need to be installed on each downstream Cluster, for the nodes to be initialized correctly.
For this example we are also going to install Calico as the default CNI.

We can do this automatically at Cluster creation using the Cluster API Add-on Provider Fleet.
This Add-on provider is installed by default with Rancher Turtles.
Two HelmApps need to be created first, to be applied on the new Cluster via label selectors.
```
kubectl apply -f https://raw.githubusercontent.com/rancher/turtles/refs/heads/main/examples/applications/ccm/azure/helm-chart.yaml
kubectl apply -f https://raw.githubusercontent.com/rancher/turtles/refs/heads/main/examples/applications/cni/calico/helm-chart.yaml
```

Create the Azure Cluster from the example ClusterClass

Note that some variables are left to the user to substitute.
Also beware that the internal-first registrationMethod variable is used as a workaround for correct provisioning.
This immutable variable however will lead to issues when scaling or rolling out control plane nodes.
A patch will support this case in a future release of CAPZ, but the Cluster will need to be reprovisioned to change the registrationMethod

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  labels:
    cluster-api.cattle.io/rancher-auto-import: "true"
    cloud-provider: azure
    cni: calico
  name: azure-quickstart
spec:
  clusterNetwork:
    pods:
      cidrBlocks:
      - 192.168.0.0/16
  topology:
    class: azure-rke2-example
    controlPlane:
      replicas: 3
    variables:
    - name: subscriptionID
      value: <AZURE_SUBSCRIPTION_ID>
    - name: location
      value: <AZURE_LOCATION>
    - name: resourceGroup
      value: <AZURE_RESOURCE_GROUP>
    - name: azureClusterIdentityName
      value: cluster-identity
    - name: registrationMethod
      value: internal-first
    version: v1.31.1+rke2r1
    workers:
      machineDeployments:
      - class: rke2-default-worker
        name: md-0
        replicas: 3

An Azure AKS ClusterClass can be found among the Turtles examples.

kubectl apply -f https://raw.githubusercontent.com/rancher/turtles/refs/heads/main/examples/clusterclasses/azure/clusterclass-aks-example.yaml

Create the Azure AKS Cluster from the example ClusterClass

Note that some variables are left to the user to substitute.

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  labels:
    cluster-api.cattle.io/rancher-auto-import: "true"
  name: azure-aks-quickstart
spec:
  clusterNetwork:
    pods:
      cidrBlocks:
      - 192.168.0.0/16
  topology:
    class: azure-aks-example
    variables:
    - name: subscriptionID
      value: <AZURE_SUBSCRIPTION_ID>
    - name: location
      value: <AZURE_LOCATION>
    - name: resourceGroup
      value: <AZURE_RESOURCE_GROUP>
    - name: azureClusterIdentityName
      value: cluster-identity
    version: v1.31.1
    workers:
      machinePools:
      - class: default-system
        name: system-1
        replicas: 1
      - class: default-worker
        name: worker-1
        replicas: 1