When inspecting a Cluster API (CAPI) management cluster with kubectl, the number of Custom Resource Definitions (CRDs) can feel overwhelming: Cluster, Machine, MachineDeployment, KubeadmControlPlane, and various provider objects.
You do not need to master the entire specification to navigate with confidence. Cluster API organizes resources into a predictable hierarchy. By understanding the core resource graph, you can inspect any running cluster with kubectl, recognize what each object does, and understand how the pieces connect.
The Kubernetes analogy
If you understand native Kubernetes workload objects, you already understand how Cluster API structures worker nodes:
Deployment → MachineDeployment
ReplicaSet → MachineSet
Pod → Machine
In Kubernetes, a Deployment manages declarative rollouts across ReplicaSet objects, a ReplicaSet ensures a desired count of Pod replicas, and a Pod represents a containerized workload.
Cluster API applies this exact pattern to infrastructure hosts:
MachineDeploymentmanages worker rollouts and configuration updates.MachineSetmaintains the target count of identical worker machines.Machinemanages the lifecycle of a single host system.
While this analogy provides an immediate mental anchor, the analogy is useful but not exact:
- Lifecycle timing: Creating or deleting a
Podtakes seconds within a kernel. Provisioning aMachineinvolves cloud API calls, OS booting, and initialization scripts, taking minutes. - Resource weight: Pods share kernel resources. Machines provision dedicated hypervisors, disks, and interfaces with direct infrastructure costs.
- State safety: Deleting a
Podreschedules a container. Deleting aMachinedestroys a host, requiring node cordoning, draining, and etcd quorum preservation.
The core resource graph
Every Cluster API cluster revolves around a single hierarchical tree, regardless of the underlying infrastructure provider:
Cluster
├── KubeadmControlPlane
│ └── Machine
│ ├── BootstrapConfig
│ └── InfrastructureMachine
│
└── MachineDeployment
└── MachineSet
└── Machine
├── BootstrapConfig
└── InfrastructureMachine
The graph divides into two branches beneath the root Cluster:
- The Control Plane branch: Managed by
KubeadmControlPlane, which directly supervisesMachineobjects to safeguard etcd quorum. - The Worker branch: Managed by
MachineDeploymentandMachineSet, which scale and roll out workerMachineobjects using standard deployment patterns.
At the bottom of both branches, every Machine delegates execution to a BootstrapConfig for node initialization and an InfrastructureMachine for server provisioning.
The major objects explained
To navigate a cluster effectively with kubectl, you only need to understand these core objects:
Cluster
The Cluster object is the root anchor for the workload cluster. It defines cluster-wide networking, such as Pod and Service CIDR blocks, and references the control plane and infrastructure providers. While it does not provision compute directly, every other resource in the cluster links back to it.
KubeadmControlPlane
The KubeadmControlPlane manages the lifecycle, scaling, and rolling upgrades of control plane nodes. Unlike worker nodes, it directly creates and supervises individual Machine objects without an intermediate MachineSet to protect etcd quorum. It automatically coordinates certificates, join tokens, and version upgrades across control plane members.
MachineDeployment
The MachineDeployment manages declarative rollouts and scaling for worker nodes, mirroring the Kubernetes Deployment. When you change worker configurations, such as machine images or instance sizes, it coordinates an automated rolling replacement. It implements these rollouts by creating and updating underlying MachineSet objects.
MachineSet
The MachineSet guarantees that a configured number of identical worker Machine objects are running, behaving like a ReplicaSet. It reacts to replica changes by creating or deleting individual Machine resources. Operators rarely modify MachineSets directly, interacting instead with the parent MachineDeployment.
Machine
The Machine represents the declarative lifecycle of a single compute host, serving as the counterpart to a Pod. It tracks an individual host through phases such as provisioning, running, and deletion. Rather than managing cloud APIs directly, the Machine delegates work by referencing an InfrastructureMachine and a BootstrapConfig.
BootstrapConfig
The BootstrapConfig (commonly KubeadmConfig) generates the initialization data—such as cloud-init scripts and join tokens—needed to turn a raw server into a Kubernetes node. It writes this payload into a Kubernetes Secret that the infrastructure provider passes to the instance at boot. Once the node joins the cluster, its primary job is complete.
InfrastructureMachine
The InfrastructureMachine (such as AWSMachine or AzureMachine) represents the provider-specific compute resource backing a Machine. It captures environment-specific attributes such as instance type, disk layout, subnets, and security groups. The corresponding infrastructure controller reconciles this object by calling cloud APIs to create or terminate the VM.
Templates
Templates (such as AWSMachineTemplate and KubeadmConfigTemplate) act as reusable, immutable blueprints for creating per-machine resources. Because each machine requires its own dedicated infrastructure object and bootstrap secret, controllers cannot reference static machine instances. Instead, controllers stamp out new concrete objects from these templates as replicas scale.
Note on MachinePool: Some cloud providers offer native auto-scaling worker groups (such as AWS Auto Scaling Groups or Azure Scale Sets). Cluster API supports these through an alternative
MachinePoolabstraction, where the cloud provider manages the fleet as a single pool rather than CAPI reconciling individualMachineobjects.
Templates: Blueprints for concrete objects
A common question when inspecting CAPI resources is why both AWSMachine and AWSMachineTemplate exist.
A concrete resource like AWSMachine represents one specific VM. If a MachineDeployment has three replicas, it cannot point to a single AWSMachine, because each host requires its own unique instance ID, private IP, and initialization secret.
Instead, controllers reference templates:
Template
↓
Concrete per-Machine object
When a controller creates a machine, it reads the referenced template to stamp out a dedicated InfrastructureMachine and BootstrapConfig for that Machine.
Templates are immutable. When updating worker nodes—such as changing VM sizes or OS images—you create a new template and point the MachineDeployment to it. The controller initiates a rolling replacement, creating new machines from the new template and retiring old ones.
References vs. OwnerReferences
Cluster API manifests link objects in two ways:
- Contract references (
spec.*Ref): Explicit pointers in an object’s spec (like aMachinepointing to itsAWSMachine). Controllers read these references to locate functional dependencies. - Owner references (
metadata.ownerReferences): Standard Kubernetes metadata establishing parent-child hierarchies. Kubernetes uses owner references for cascading deletion—deleting aClusterautomatically deletes childMachineSets,Machines, and cloud resources.
Navigating the graph with kubectl
With this mental model in place, you can navigate any Cluster API environment with kubectl by following the hierarchy:
- Cluster intent:
kubectl get clusterverifies overall cluster readiness. - Rollouts and replicas:
kubectl get kubeadmcontrolplane,machinedeploymentchecks control plane and worker fleet health. - Individual hosts:
kubectl get machinesinspects host lifecycle phases. - Provider and bootstrap resources:
kubectl get awsmachines,kubeadmconfigsinspects underlying VMs and bootstrap data.
Instead of navigating dozens of disconnected CRDs, you trace directly from cluster intent down to individual hosts.
Quick reference
Cluster = cluster-level intent MachineDeployment = worker rollout MachineSet = worker replicas Machine = one host lifecycle BootstrapConfig = node bootstrap InfrastructureMachine = provider infrastructure Template = blueprint for future objects