Cluster API — declarative Kubernetes cluster lifecycle

Cluster API (CAPI) is the Kubernetes-native way to manage Kubernetes clusters as Kubernetes objects. A CAPI control plane watches Cluster and Machine CRs and provisions workload clusters via infrastructure providers. This lesson walks the CAPI architecture, the providers, the GitOps integration, and the operational discipline.

The CAPI architecture

flowchart LR
    A[Bootstrap cluster] --> B[CAPI controllers]
    B --> C["Infrastructure provider: AWS / Azure / GCP"]
    C --> D[Workload cluster]
    B --> E["Bootstrap provider: KubeadmControlPlane"]
    E --> D
    B --> F[Cluster CR]
    B --> G[Machine CR]
    B --> H[MachineDeployment CR]

The components:

• Bootstrap cluster — a Kubernetes cluster where CAPI runs. Often a management cluster separate from workload clusters.
• CAPI controllers — Deployments in the bootstrap cluster that watch Cluster, Machine, and MachineDeployment CRs.
• Infrastructure provider — the cloud-specific implementation (CAPA for AWS, CAPZ for Azure, CAPG for GCP, CAPV for vSphere).
• Bootstrap provider — KubeadmControlPlane for kubeadm-based bootstrapping.
• Cluster, Machine, MachineDeployment — the CRDs that declare the desired cluster state.

The CRDs

flowchart LR
    A[Cluster] --> B["ControlPlane: KubeadmControlPlane"]
    A --> C["Infrastructure: AWSCluster / AzureCluster"]
    A --> D["Workers: MachineDeployment"]
    D --> E[MachineSet]
    E --> F[Machine]
    F --> G["Infrastructure: AWSMachineTemplate"]
    F --> H["Bootstrap: KubeadmConfigTemplate"]

• Cluster — the top-level object; references the control plane and infrastructure.
• KubeadmControlPlane — the control-plane implementation; declares the desired number of control-plane nodes.
• MachineDeployment — the worker node group; declares the desired number of worker nodes and their template.
• Machine — an individual node; references the infrastructure and bootstrap templates.

A CAPI cluster declaration

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: prod-cluster-1
  namespace: capi-system
spec:
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    name: prod-cluster-1-control-plane
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
    kind: AWSCluster
    name: prod-cluster-1
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
kind: AWSCluster
metadata:
  name: prod-cluster-1
  namespace: capi-system
spec:
  region: us-east-1
  sshKeyName: capi-key
  controlPlaneLoadBalancer:
    scheme: internet-facing

The Cluster references the KubeadmControlPlane (for control-plane nodes) and AWSCluster (for AWS infrastructure). CAPI reconciles the actual state toward the declared state.

The providers

The provider choice depends on the infrastructure. For hybrid or multi-cloud, multiple providers can coexist in the same CAPI control plane.

The GitOps integration

flowchart LR
    A[Git repository] --> B["Argo CD / Flux"]
    B --> C[Bootstrap cluster]
    C --> D[CAPI controllers]
    D --> E[Workload cluster]
    E --> F["Argo CD / Flux"]
    F -->|watches Git| E

CAPI integrates with GitOps:

1. The bootstrap cluster has Argo CD or Flux installed.
2. The Git repository contains the Cluster, KubeadmControlPlane, and MachineDeployment YAMLs.
3. Argo CD applies them to the bootstrap cluster.
4. CAPI provisions the workload cluster.
5. The workload cluster has Argo CD installed (via CAPI’s bootstrap provider).
6. The workload cluster’s Argo CD applies the application manifests from Git.

The bootstrap cluster is the cluster’s cluster; the workload cluster is the cluster’s clusters.

The operational failure modes

CAPI fails in production for predictable reasons:

• Bootstrap cluster unavailable. CAPI cannot manage clusters if the bootstrap cluster is down. A HA bootstrap cluster (3 nodes) is required.
• Provider credentials missing. The AWSCluster or AzureCluster CR references credentials that are not configured. CAPI cannot provision nodes.
• Cluster deletion stuck. Deleting a Cluster CR should cascade-delete all child objects. If a child is stuck (e.g., a node that cannot be drained), the Cluster deletion hangs.
• KubeadmControlPlane version skew. The kubeadm version in the KubeadmControlPlane does not match the workload cluster’s kubelet version. Upgrades fail.
• GitOps reconciliation issues. Argo CD cannot reconcile the CAPI CRs because of RBAC or webhook issues.

Quiz

Production discipline

Cluster API in production rests on five non-negotiable elements:

• HA bootstrap cluster. A 3-node bootstrap cluster dedicated to CAPI. A single-node bootstrap is a single point of failure.
• All three components installed. Core CAPI, bootstrap provider, infrastructure provider. Missing any one breaks provisioning.
• GitOps for cluster lifecycle. Argo CD or Flux applies the CAPI CRs from Git. The bootstrap cluster is GitOps-managed too.
• Test in staging. A CAPI cluster that has never been provisioned in staging may fail in production with provider-specific errors.
• Document the CAPI topology. The architecture diagram must show the bootstrap cluster, the workload clusters, the providers, and the GitOps flow.

CAPI is the Kubernetes-native way to manage Kubernetes clusters. The discipline is to treat CAPI as production infrastructure with its own HA, GitOps, and testing requirements.