Cluster API: Declarative Kubernetes Cluster Lifecycle Management Across Providers

The problem Cluster API solves for platform operators

Most teams end up managing Kubernetes clusters with a pile of scripts, a Terraform state file and a runbook. That works until you have clusters in three environments and need to upgrade them all. Cluster API exists to move that work into the Kubernetes control loop. The README describes the project as providing "declarative APIs and tooling to simplify provisioning, upgrading, and operating multiple Kubernetes clusters", and it is explicit about the audience: platform operators.

The design bet is that infrastructure objects (virtual machines, networks, load balancers, VPCs) and the Kubernetes cluster configuration should be described the same way application developers describe workloads. If you already run controllers and reconcile custom resources, the operational model is familiar. If your team has never written a controller or debugged a reconcile loop, the learning curve is real, because a failed cluster creation surfaces as a status condition on a custom resource, not as an error message from a CLI.

This is a SIG Cluster Lifecycle subproject, so the governance and release process follow Kubernetes conventions rather than a single vendor's roadmap. The repository is not archived, and the last push was on 2026-09-23, with v1.14.2 and v1.13.6 both released on 2026-09-08. Two maintained minor lines is the practical signal here: you are expected to move between minor versions, not sit on one indefinitely.

How the management cluster and provider model fit together

Cluster API does not talk to hypervisors directly. It defines cluster-level custom resources and delegates the infrastructure work to providers. The README states that Cluster API "can be extended to support any infrastructure (AWS, Azure, vSphere, etc.), bootstrap or control plane (kubeadm is built-in) provider", and points at a growing list of supported providers in the book.

The repository layout reflects that split. The api/ directory holds the API types, bootstrap/ contains the kubeadm bootstrap provider, controlplane/ contains the kubeadm control plane provider, controllers/ holds the core controllers, and exp/ carries experimental APIs. A provider ships its own controllers and CRDs, and the core controllers reconcile the shared objects that tie them together.

The practical consequence: a Cluster object references an infrastructure cluster and a control plane object, and those reference machine templates and bootstrap configs. Nothing happens until a provider controller is running and watching for its own resource kinds. This is why installing Cluster API alone gives you an empty system. The core components reconcile; the provider does the provisioning. The documentation's provider reference page is the place to confirm which providers exist, since the README only names AWS, Azure and vSphere as examples.

Installing Cluster API and creating a first cluster

The README does not carry install commands. It points to the Book at cluster-api.sigs.k8s.io, and specifically to the Quick Start page, for getting started. Check the Quick Start for the current prerequisites, because the exact provider and version you pick changes the commands, and the repository files here do not spell them out.

What the repository does show is how the project is built. The Makefile sets the Go toolchain and the Dockerfile builds the manager binary from a builder image passed at build time. The Dockerfile comments give the invocation directly:

# Run this with docker build --build-arg builder_image=<golang:x.y.z>

The same file documents the argument that selects which manager to compile, so the control plane and bootstrap providers can be built from the same Dockerfile:

ARG package=.

And the comment above it shows the alternative values:

# Run this with docker build --build-arg package=./controlplane/kubeadm or --build-arg package=./bootstrap/kubeadm

For end users, the path is the Book's Quick Start rather than these build steps. The README's "Useful links" list points there, and the Quick Start is where the management cluster initialization and workload cluster creation steps live. Read it before planning a rollout, since the provider you choose determines everything that follows.

Where Cluster API is the wrong tool

The first limitation is provider dependency. Cluster API without a provider does nothing useful, and provider quality varies. The README says there is a growing list of supported providers but does not guarantee parity between them. If your infrastructure is niche, check the provider reference before you plan anything.

Second, this is not a single-cluster tool. If you run one cluster on one cloud and upgrade it twice a year, the management cluster, the provider controllers and the CRD surface are overhead you will pay for continuously. A scripted upgrade is simpler and has fewer moving parts.

Third, there is no UI in this repository. The related searches include "Cluster API UI", but the top-level entries show no frontend: the components are Go binaries, controllers and CRDs. Any graphical experience comes from a separate project, not from Cluster API itself.

Fourth, the upgrade path is coupled. Releases v1.14.2 and v1.13.6 landed on the same day, which indicates parallel maintenance of two minor lines rather than a single supported version. Moving from one minor to the next involves upgrading the core components and the providers together. The documentation covers upgrade procedures; the README does not document rollback, so treat reversibility as something to confirm in the Book before you upgrade production clusters.

Cluster API versus Terraform and Crossplane

The related searches put Cluster API against Terraform and Crossplane, and the difference is architectural rather than feature-level.

Terraform applies a plan and exits. State lives in a backend file, and drift is detected when you run the next plan. Cluster API runs controllers that reconcile continuously, so a machine that disappears is replaced without anyone running a command. That is the trade: continuous reconciliation means a persistent control plane with its own upgrade cadence, while Terraform means no always-on component but no self-healing either.

Crossplane also uses Kubernetes controllers and custom resources, so the surface looks similar. The distinction is scope. Crossplane targets managed cloud services generally through its provider model; Cluster API targets Kubernetes cluster lifecycle specifically, with providers that understand machines, control planes and bootstrap configuration. If your goal is provisioning databases and buckets alongside clusters, Crossplane's model is broader. If your goal is the cluster lifecycle itself, Cluster API's resources are shaped for exactly that, and its provider ecosystem is organized around it.

Neither comparison is settled by benchmarks. The deciding question is whether you want a control loop that owns cluster state continuously or a pipeline that applies changes on demand.

Maintenance, licensing and upgrade cost

The repository is Apache-2.0, the same licence Kubernetes uses. That permits commercial use and modification, and it carries the usual obligations around notices and attribution. This is a description of the licence identifier, not legal advice; read LICENSE and your own counsel's guidance before redistributing.

The maintenance picture from the repository facts: not archived, last push 2026-09-23, with v1.14.2, v1.13.6 and v1.14.1 released across September 2026. Two minor lines receiving releases on the same day is a signal about how much upgrade work you are signing up for. You are not adopting a frozen artifact; you are adopting a component that expects periodic upgrades.

Upgrade cost lands in three places. The core components, the providers, and the workload clusters themselves. Because providers are versioned independently, a CAPI upgrade can require a matching provider upgrade, and the provider's own release notes are where that compatibility is stated. The repository includes a CHANGELOG/ directory and a version/ directory, which is where release-specific detail lives. Budget the upgrade as a coordinated event rather than a background task. The go.mod pins Kubernetes libraries at v0.37.0 and Go at 1.26.0, so building from source requires a toolchain that satisfies those versions; the Makefile sets GO_VERSION to 1.26.6.

Editorial conclusion

Adopt Cluster API when you run Kubernetes across several infrastructure environments and want one control plane to reconcile them, and when you can commit to managing provider controllers and their upgrade cadence. Do not adopt it if you only operate a single cluster on one cloud, or if you expect a web console: there is no UI in this repository. Before committing, verify that a provider exists for your infrastructure, check the provider's own release notes against the CAPI version you plan to run, and read the Quick Start at cluster-api.sigs.k8s.io to confirm the current prerequisites for your environment.

Frequently asked questions

Official sources

1. kubernetes-sigs/cluster-api on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases