Managing Kubernetes clusters declaratively requires orchestrating very different systems: allocating cloud compute, provisioning virtual networks, injecting bootstrapping scripts, and managing etcd quorum. A single monolithic controller handling all of these concerns across dozens of cloud platforms and operating systems would be brittle and unmaintainable.
Cluster API (CAPI) solves this by decomposing cluster lifecycle into modular, cooperating controllers that run inside a dedicated management cluster. Instead of tightly coupling these controllers through direct RPCs or internal APIs, Cluster API uses the Kubernetes API itself as its coordination backbone.
Architecture at a glance
In a Cluster API deployment, the management cluster hosts the custom resources describing target workload clusters, alongside the controllers that reconcile them.
flowchart TB
subgraph ManagementCluster["Management Cluster"]
API["Kubernetes API<br/>(Coordination Layer & State Store)"]
CORE["CAPI Core<br/>(Cluster & Machine Lifecycle)"]
BOOT["Bootstrap Provider<br/>(Node Initialization Data)"]
CP["Control Plane Provider<br/>(Control Plane Lifecycle)"]
INFRA["Infrastructure Provider<br/>(VMs, Networks, Load Balancers)"]
API <--> CORE
API <--> BOOT
API <--> CP
API <--> INFRA
end
The architecture centers entirely on the Kubernetes API. Rather than running as a monolith, Cluster API divides work across four specialized controller domains: Core, Infrastructure, Bootstrap, and Control Plane. Each controller runs in its own process, watches specific Custom Resource Definitions (CRDs), and interacts exclusively through the API server.
The four responsibilities
Cluster API divides cluster management into four distinct responsibilities, each owned by an independent controller:
1. Core: Generic cluster and machine lifecycle
The core provider manages generic lifecycle semantics for clusters and machines. It is completely agnostic to specific cloud providers, hypervisors, and operating systems.
- Owns: High-level abstractions such as
Cluster,Machine,MachineSet,MachineDeployment, andMachineHealthCheck. - Role: Handles scaling algorithms, rollout strategies, node health monitoring, and machine lifecycle phases. It coordinates when machines must be created or deleted, delegating environment-specific actions to providers via object references.
2. Infrastructure: VMs, networking, and provider-specific resources
The infrastructure provider provisions and manages physical and cloud resources. It interfaces directly with cloud APIs, hypervisors, or bare-metal provisioning engines.
- Owns: Provider-specific resources such as infrastructure cluster objects (e.g.,
AWSCluster,AzureCluster,GCPCluster,VSphereCluster) and infrastructure machine objects (e.g.,AWSMachine,AzureMachine,VSphereMachine). - Role: Provisions virtual machines, VPCs, subnets, route tables, security groups, and control-plane load balancers. Once an instance is running and reachable, the infrastructure controller reports its status back to the API.
3. Bootstrap: Turning a host into a Kubernetes node
The bootstrap provider generates the configuration data required to convert a raw compute instance into a functioning Kubernetes node.
- Owns: Bootstrap configuration resources, such as
KubeadmConfigor provider equivalents. - Role: Generates initialization artifacts, such as
cloud-initscripts, Ignition configs, or join tokens (e.g., viakubeadm). It writes this data into a KubernetesSecretin the management cluster, which the infrastructure provider injects into the machine during provisioning.
4. Control Plane: Control-plane lifecycle
The control plane provider oversees the creation, scaling, health, and upgrades of the target cluster’s control plane.
- Owns: Control plane resources, such as
KubeadmControlPlane. - Role: Orchestrates initial control plane bootstrapping, etcd cluster membership, ordered replica additions for high availability, and rolling Kubernetes version upgrades. It translates control plane intent into individual
Machineand bootstrap resources.
Provider Contracts
Because CAPI core cannot have hardcoded compile-time dependencies on cloud SDKs or bootstrapping tools, it interacts with providers through Provider Contracts.
A provider contract defines the expected CRD schemas, mandatory status fields (such as status.ready), and behavioral rules that an external provider must fulfill. As long as an external provider implements these standardized contracts, CAPI core can manage its lifecycle seamlessly. This interface boundary allows operators to swap infrastructure, bootstrap, or control plane providers without modifying core CAPI code.
How controllers cooperate
Cluster API controllers do not communicate with each other directly. There are no gRPC endpoints, internal RPCs, or webhooks linking the core controller to the infrastructure or bootstrap controllers.
Instead, controllers generally coordinate by reading and writing Kubernetes API objects and status instead of directly invoking each other.
Every controller runs a standard Kubernetes reconciliation loop:
- Watch: The controller uses Kubernetes informers to watch its own custom resources and referenced objects.
- Read: When an event occurs, the controller reads the current specification and status from the API server.
- Reconcile: The controller performs its domain-specific work—such as generating a bootstrap secret or calling a cloud API to launch a virtual machine.
- Update Status: The controller writes the result back into the resource’s
.statusfield. - Trigger: The status change is recorded in etcd, triggering informers for other controllers that depend on that resource to run their next reconciliation step.
Why the Kubernetes API is the coordination layer
Using the Kubernetes API as the coordination layer provides critical distributed systems properties:
- Decoupled execution: Controllers run as independent processes. They need no knowledge of other controllers’ deployment topology, internal memory, or operational lifecycle.
- Resilience and eventual consistency: If a cloud provider controller crashes, faces API rate limits, or loses network access, other controllers continue operating normally. When connectivity recovers, the reconciliation loop brings actual infrastructure into alignment with desired state.
- Single source of truth: Desired state and observed state are durably stored in etcd. Every transition, condition, and status update is auditable and queryable.
- Standard tooling and RBAC: Operators interact with, inspect, and secure the entire cluster lifecycle using native Kubernetes tools like
kubectl, standard RBAC policies, and admission webhooks.
Why this separation matters
This modular architecture delivers key practical benefits:
- True composability: Core cluster and machine lifecycle logic remains identical regardless of the target environment. You can target AWS, Azure, Google Cloud, VMware vSphere, or bare metal without altering deployment patterns.
- Isolated failure domains: An API rate limit or outage in an infrastructure provider does not affect control plane quorum management or prevent core controllers from queuing desired state changes.
- Extensibility without forks: Third parties and enterprise platform teams can implement custom infrastructure or bootstrap providers to support proprietary hardware or custom operating systems without modifying upstream CAPI binaries.
- Clean team boundaries: Cloud and network specialists can manage infrastructure provider configurations and IAM policies, while platform operators focus on cluster topologies and machine rollout strategies.
Remember
- The management cluster hosts all CAPI controllers and serves as the declarative control plane for target workload clusters.
- Responsibilities are split across four distinct controller roles: Core, Infrastructure, Bootstrap, and Control Plane.
- Controllers never invoke each other directly; they coordinate asynchronously by reading and writing Kubernetes custom resources.
- Provider contracts define standard interfaces between CAPI core and providers, enabling modular plug-and-play implementations.
- Continuous reconciliation loops provide eventual consistency and self-healing against transient infrastructure failures.