Cluster management

Cluster API

1.What is Cluster API ?

A SIG Cluster Lifecycle sub-project. Whole clusters become custom resources : create, scale, upgrade and delete them declaratively, on cloud or on-prem.

  • One CRD API instead of a different tool per installer and cloud.
  • Controllers reconcile it, like any operator.
Two kinds of cluster
  • Management : runs the CAPI and provider controllers, and holds the Cluster and Machine objects.
  • Workload : the cluster those objects describe. Your apps run there, CAPI does not.

v1.14.2 (2026-09-08), API v1beta2. Workload clusters v1.31 to v1.37.

2.Bootstrap and pivot

A throwaway kind cluster builds the real management cluster, then hands over.

  1. Create a temporary kind cluster.
  2. clusterctl init : kind can now manage clusters.
  3. Apply the target cluster's YAML. Wait for it.
  4. Get its kubeconfig, clusterctl init there.
  5. clusterctl move : pause, copy, resume.
  6. Delete kind. The target manages itself.

move is not backup and restore.

Your laptop clusterctl, kubectl kind cluster temporary 1-2 create, init 6 delete at the end 4 kubeconfig, init again 5 clusterctl move 3 provisions the target Management cluster CAPI core + providers Infrastructure API AWS, Azure, vSphere VMs, LBs networks Workload A Workload B Machines become Nodes, + a kubeconfig Secret

3.Core objects

  • Cluster : pod and service CIDRs, serviceDomain. Refs to its InfraCluster and its control plane.
  • KCP (KubeadmControlPlane) : control plane Machines, etcd membership, certificates.
  • Machine : one host, one Node (status.nodeRef).
  • Templates : each new Machine gets its own clones of an InfraMachineTemplate and a KubeadmConfigTemplate. Treat them as immutable : copy, then repoint the ref.
AWSCluster InfraCluster Cluster CIDRs, domain KCP like StatefulSet infrastructureRef controlPlaneRef MachineDeployment like Deployment MHC health check old + new selects, deletes MachineSet like ReplicaSet Machine like Pod owns N owns CP Machines infrastructureRef configRef nodeRef AWSMachine InfraMachine KubeadmConfig bootstrap Secret Node workload

4.Same pattern as workloads

CAPI objectLikeJob
MachinePodOne host, one Node. Never edited : its owner replaces it
MachineSetReplicaSetKeeps N Machines. Not used directly
MachineDeploymentDeploymentRolls a template change across an old and a new MachineSet
KubeadmControlPlaneStatefulSetControl plane Machines and etcd. Upgrade with spec.version
MachinePoolASG, VMSSHands workers to a provider-native group. Beta, on by default
MachineHealthCheckauto-repairDeletes unhealthy Machines owned by a MachineSet or KCP

5.Providers

  • Infrastructure : VMs, networks, load balancers.
  • Bootstrap : CABPK, kubeadm and cloud-init.
  • Control plane : KCP. Also IPAM and add-on (Helm) providers.
  • clusterctl init adds core, kubeadm bootstrap and KCP by default. The CAPI Operator uses CRDs instead.
Infra providerFlagNotes
CAPA v2.13.1awsEKS too. IAM via clusterawsadm
CAPZ v1.27.0azureAKS too. Azure Service Operator
CAPV v1.17.0vsphereOVA images v1.30 to v1.37
CAPM3 v1.14.1metal3Bare metal, bring Ironic
CAPDdockerDevelopment and tests only

Flag = clusterctl init --infrastructure <name>.

In short : A management cluster reconciles Cluster and Machine objects into real clusters through providers, the way Deployments turn into Pods.

1.ClusterClass and managed topology

A ClusterClass bundles templates, variables and patches. A Cluster then sets only spec.topology. The ClusterTopology gate is alpha and off in v1.14 : export CLUSTER_TOPOLOGY=true before clusterctl init.

apiVersion: cluster.x-k8s.io/v1beta2
kind: Cluster
metadata: { name: capi-quickstart }
spec:
  topology:
    classRef: { name: my-class-v1 }
    version: v1.37.0   # bump to upgrade
    controlPlane: { replicas: 3 }  # odd for etcd
    workers:
      machineDeployments:
      - class: default-worker
        name: md-0
        replicas: 3
Cluster spec.topology ClusterClass variables + patches classRef templateRef KCP template InfraCluster template InfraMachine templates KubeadmConfig template version, replicas Topology controller ClusterTopology gate clones + patches creates and owns KCP + InfraCluster MachineDeployment one per workers entry MHCs from healthCheck Edit the Cluster, never the generated objects.

2.Upgrades replace Machines

A new Machine joins, then the old one is drained and deleted. Control plane first, then workers.

  • Topology : change only spec.topology.version. Since v1.12 it can chain minors from ClusterClass spec.kubernetesVersions.
  • Rollout : RollingUpdate (maxSurge 1, maxUnavailable 0) or OnDelete (MD only). spec.rollout.after forces one.
  • In-place (alpha, v1.12) : an update extension changes Machines without replacing them.
Bump the version spec.topology.version 2+ minors Upgrade plan chained, topology only each minor KCP rollout control plane first may skip minors Worker rollout MachineDeployments Machine image must match the version Without a topology 1. KCP spec.version 2. each MachineDeployment one minor at a time, no upgrade plan New MachineSet up by maxSurge (1) Old MachineSet down, maxUnavailable 0 Old Machine drain, delete infra, Node

3.Commands

CommandDoes
clusterctl init --infrastructure dockerMake this a management cluster. Export gates first
clusterctl generate cluster capi-quickstart --flavor development --kubernetes-version v1.37.0 > capi-quickstart.yamlRender a template from the provider repo. --list-variables shows what it needs
clusterctl describe cluster capi-quickstartTree of the Cluster and its Machines, surfacing problems
clusterctl get kubeconfig capi-quickstart > capi.kubeconfigAdmin kubeconfig, from the <name>-kubeconfig Secret
clusterctl move --to-kubeconfig=mgmt.kubeconfig --dry-runPivot. The target needs the same or newer providers
kubectl patch cluster capi-quickstart --type json -p '[{"op":"replace", "path":"/spec/topology/version", "value":"v1.37.1"}]'Upgrade a topology cluster, control plane first
kubectl delete cluster capi-quickstartTeardown. Cascades through the infrastructure in order
Gotchas
  • Never kubectl delete -f cluster.yaml : infrastructure can be left behind.
  • clusterctl upgrade upgrades providers and CRDs, never a cluster's Kubernetes.
  • No CNI, no Ready nodes. CAPI installs none.
  • nodeDrainTimeoutSeconds 0 = no limit. A PDB can stall a rollout.
Good to know
  • Add-ons : ClusterResourceSet (GA) applies a CNI by label. CAAPH installs Helm charts.
  • GitOps : Flux applies the Cluster YAML. A Kustomization with kubeConfig.secretRef <cluster>-kubeconfig deploys into the workload cluster.
  • v1beta2 Cluster and Machine refs use apiGroup, not apiVersion. v1beta1 stops being served in v1.16.
In short : A ClusterClass holds the shape, the Cluster holds version and replicas, and upgrades replace Machines.