Using Rancher’s Cluster API Toggle to Provision Clusters as CAPI Resources

Enable Rancher’s Cluster API toggle

Starting with Rancher 2.7+ you can turn on the Cluster API (CAPI) toggle while creating a cluster. When the toggle is on, Rancher treats the cluster as a set of CAPI custom resources (Cluster, Infrastructure, Machine) that live in the cluster-api-system namespace of the management cluster.

Worked example: creating a K3s cluster via the Rancher CLI

1. Ensure you have the Rancher CLI authenticated to a management cluster running Rancher 2.7+.
2. Create a file k3s-cluster.yaml with the minimal CAPI manifests for a K3s workload cluster.

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: 
  namespace: cluster-api-system
spec:
  clusterNetwork:
    pods:
      cidrBlocks: ["10.244.0.0/16"]
    services:
      cidrBlocks: ["10.96.0.0/12"]
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: DockerCluster
    name: 
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: DockerCluster
metadata:
  name: 
  namespace: cluster-api-system
spec: {}
---
apiVersion: cluster.x-k8s.io/v1beta1
kind: Machine
metadata:
  name: -control-plane-0
  namespace: cluster-api-system
spec:
  clusterName: 
  version: "v1.28.0"
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: DockerMachine
    name: -control-plane-0
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: DockerMachine
metadata:
  name: -control-plane-0
  namespace: cluster-api-system
spec: {}

Apply the manifests:

kubectl apply -f k3s-cluster.yaml

Rancher watches the cluster-api-system namespace and reconciles the resources, provisioning the underlying nodes.

Verifying the cluster is managed by CAPI

• In the Rancher UI, navigate to Cluster Management → Clusters. The newly created cluster should appear with a CAPI icon.
• Run kubectl get clusters -n cluster-api-system to see the Cluster object in Ready state.
• Check the associated Machine objects: kubectl get machines -n cluster-api-system.

Limits and common mistakes

• Supported providers: The toggle works with K3s, RKE (v1), and infrastructure providers such as vSphere, OpenStack, Bare‑metal, and kubeadm. It is not available for Rancher‑managed RKE2 clusters that bypass CAPI.
• RBAC requirements: The service account or user creating the cluster must have get, list, watch, create, update, patch, delete permissions on the CAPI CRDs in cluster-api-system. Missing permissions cause the UI to show an error or the CLI to time out.
• Manual imports: Clusters imported into Rancher after creation are not converted to CAPI resources; they lose the lifecycle benefits of the toggle.
• Mis‑configured Infrastructure spec: Supplying an incorrect API version, missing required fields, or referencing a non‑existent machine template leaves the Cluster object in Pending indefinitely. Verify the manifests against the provider’s CAPI provider documentation.
• Unsupported provider: Enabling the toggle for a provider that does not implement a CAPI provider (e.g., trying to use RKE2 with CAPI) leads to version conflicts and the cluster may never reach Ready.

Practical way to check the result

After applying the manifests, run:

kubectl get clusters -n cluster-api-system -o wide

Look for the READY column to show true. If it stays false, inspect the events:

kubectl describe cluster  -n cluster-api-system

Rollback (deleting the cluster)

Because creating a cluster via CAPI creates mutable objects, you can remove it cleanly:

• From the Rancher UI: select the cluster and click Delete.
• Or with kubectl: kubectl delete cluster -n cluster-api-system

Deleting the Cluster CRD triggers the CAPI controller to clean up the associated Machine and Infrastructure resources.