Cluster API (CAPI) Cheat Sheet

Updated 2026-05-22

Next Topic: Container Base Images Cheat Sheet

Cluster API (CAPI) is a Kubernetes sub-project under SIG Cluster Lifecycle that uses declarative, Kubernetes-style APIs to automate the full lifecycle — provisioning, upgrading, and deletion — of Kubernetes clusters across cloud, on-premises, and bare-metal environments. It solves the recurring problem of cluster-per-installer fragmentation by providing a unified API surface that any infrastructure provider can implement, keeping the same object model regardless of whether you target AWS, Azure, vSphere, or bare metal. The key mental model is management cluster controls workload clusters: a single management cluster runs CAPI controllers that reconcile the desired state of many downstream workload clusters, making fleet-wide operations — upgrades, health checks, scaling — as simple as editing a YAML resource.

What This Cheat Sheet Covers

This topic spans 15 focused tables and 124 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: Core Concepts and TerminologyTable 2: Infrastructure ProvidersTable 3: Bootstrap and Control Plane ProvidersTable 4: Core Machine PrimitivesTable 5: MachineHealthCheck — Self-Healing DetailsTable 6: ClusterClass and Managed TopologiesTable 7: clusterctl CLI CommandsTable 8: Cluster Lifecycle OperationsTable 9: MachinePool — Cloud-Native Node GroupsTable 10: Cluster Autoscaler IntegrationTable 11: ClusterResourceSet — Addon BootstrappingTable 12: GitOps Integration for Fleet ManagementTable 13: Security GuidelinesTable 14: Troubleshooting Common IssuesTable 15: Advanced Patterns and Integrations

Table 1: Core Concepts and Terminology

Every CAPI deployment involves a specific set of cluster roles and primitives. Understanding the difference between management cluster, workload cluster, and bootstrap cluster is the mandatory prerequisite for all other CAPI work.

Concept	Example	Description
Management Cluster	A Kind or K8s cluster running CAPI controllers	• The cluster where CAPI providers run and where all Cluster/Machine objects are stored • it provisions and manages all workload clusters
Workload Cluster	`kubectl get cluster -n default`	• A cluster created and managed by CAPI controllers • intended for actual workloads, not CAPI tooling
Bootstrap Cluster	A temporary Kind cluster created before the management cluster	• A temporary cluster used to provision the permanent management cluster • deleted after the pivot operation
Pivot	`clusterctl move --to-kubeconfig=mgmt.kubeconfig`	The process of moving provider components and CAPI resources from a source management cluster to a target management cluster (or from bootstrap to permanent management cluster).
Infrastructure Provider	CAPA (AWS), CAPZ (Azure), CAPG (GCP), CAPV (vSphere)	Implements provisioning of the actual VMs, networks, and load balancers for the cluster on a specific platform.

Table 1: Core Concepts and Terminology

Concept	Example	Description
Management Cluster	A Kind or K8s cluster running CAPI controllers	• The cluster where CAPI providers run and where all Cluster/Machine objects are stored • it provisions and manages all workload clusters
Workload Cluster	`kubectl get cluster -n default`	• A cluster created and managed by CAPI controllers • intended for actual workloads, not CAPI tooling
Bootstrap Cluster	A temporary Kind cluster created before the management cluster	• A temporary cluster used to provision the permanent management cluster • deleted after the pivot operation
Pivot	`clusterctl move --to-kubeconfig=mgmt.kubeconfig`	The process of moving provider components and CAPI resources from a source management cluster to a target management cluster (or from bootstrap to permanent management cluster).
Infrastructure Provider	CAPA (AWS), CAPZ (Azure), CAPG (GCP), CAPV (vSphere)	Implements provisioning of the actual VMs, networks, and load balancers for the cluster on a specific platform.