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.
- Create a temporary kind cluster.
clusterctl init: kind can now manage clusters.- Apply the target cluster's YAML. Wait for it.
- Get its kubeconfig,
clusterctl initthere. clusterctl move: pause, copy, resume.- Delete kind. The target manages itself.
move is not backup and restore.
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.
4.Same pattern as workloads
| CAPI object | Like | Job |
|---|---|---|
| Machine | Pod | One host, one Node. Never edited : its owner replaces it |
| MachineSet | ReplicaSet | Keeps N Machines. Not used directly |
| MachineDeployment | Deployment | Rolls a template change across an old and a new MachineSet |
| KubeadmControlPlane | StatefulSet | Control plane Machines and etcd. Upgrade with spec.version |
| MachinePool | ASG, VMSS | Hands workers to a provider-native group. Beta, on by default |
| MachineHealthCheck | auto-repair | Deletes 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 initadds core, kubeadm bootstrap and KCP by default. The CAPI Operator uses CRDs instead.
| Infra provider | Flag | Notes |
|---|---|---|
| CAPA v2.13.1 | aws | EKS too. IAM via clusterawsadm |
| CAPZ v1.27.0 | azure | AKS too. Azure Service Operator |
| CAPV v1.17.0 | vsphere | OVA images v1.30 to v1.37 |
| CAPM3 v1.14.1 | metal3 | Bare metal, bring Ironic |
| CAPD | docker | Development 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_ 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
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.. Since v1.12 it can chain minors from ClusterClasstopology. version spec..kubernetesVersions - Rollout : RollingUpdate (maxSurge 1, maxUnavailable 0) or OnDelete (MD only).
spec.forces one.rollout. after - In-place (alpha, v1.12) : an update extension changes Machines without replacing them.
3.Commands
| Command | Does |
|---|---|
clusterctl init --infrastructure docker | Make this a management cluster. Export gates first |
clusterctl generate cluster capi-quickstart --flavor development --kubernetes-version v1.37.0 > capi-quickstart.yaml | Render a template from the provider repo. --list-variables shows what it needs |
clusterctl describe cluster capi-quickstart | Tree of the Cluster and its Machines, surfacing problems |
clusterctl get kubeconfig capi-quickstart > capi.kubeconfig | Admin kubeconfig, from the <name>-kubeconfig Secret |
clusterctl move --to-kubeconfig=mgmt.kubeconfig --dry-run | Pivot. 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-quickstart | Teardown. Cascades through the infrastructure in order |
Gotchas
- Never
kubectl delete -f cluster.yaml: infrastructure can be left behind. clusterctl upgradeupgrades 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>-kubeconfigdeploys 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.