Cluster API turns a Kubernetes cluster into a custom resource

A cluster becomes a Cluster object with a spec and a status

Cluster API replaces imperative cluster tooling with Kubernetes-style resources. Infrastructure such as virtual machines, networks, load balancers and VPCs is described in the same declarative shape an application developer already uses for workloads, and that consistency is the point: the cluster configuration and the infrastructure under it are expressed as API objects that a controller reconciles toward a desired state.

That design targets platform operators, not individual cluster admins. The problem it solves is repetition. Provisioning clusters through provider-specific CLIs means every environment encodes the same steps differently, and an upgrade is a bespoke script per provider. Encoding a cluster as an object means the upgrade path is a change to a field, and the controller handles the ordering.

One thing to notice about how the repository presents itself: the top-level entries include `api/`, `bootstrap/`, `controlplane/`, `controllers/`, `core/` and `exp/`, and the Go module is split so that the API types live in their own module. `go.mod` declares `module sigs.k8s.io/cluster-api` with a `replace` directive pointing the API submodule back at `./api`. Consumers can therefore depend on the types without pulling the controller implementations.

Provider split: kubeadm is built in, the cloud is not

Cluster API itself ships no cloud integration. The README states that kubeadm is the built-in bootstrap provider, and that it can be extended to support any infrastructure provider such as AWS, Azure or vSphere, with a growing list of supported providers. A cluster is assembled from an infrastructure provider, a bootstrap provider, and optionally a control plane provider, each of which brings its own CRDs.

This is the sharpest structural fact about the project. You are not installing a finished cluster tool; you are installing a framework and then assembling one from parts that different teams ship on their own schedules. The supported provider list lives on the project site rather than in the repository, so the compatibility matrix is something you check per infrastructure, not per core version.

The consequence shows up on upgrade. When the core CRDs move forward, every provider in your management cluster has to match them. More than one minor line is patched in parallel, so you may end up pinned to the older line for a provider reason rather than by choice.

Where to get it: the Book and the Quick Start, not an install command

The README carries no install command. It links to the project Book and a Quick Start page at cluster-api.sigs.k8s.io, and those are where the setup procedure lives.

What the repository does show is how the manager binary is built. The Dockerfile builds the manager with a builder image passed in as an argument:

docker build --build-arg builder_image=<golang:x.y.z>

The same Dockerfile accepts `ARCH`, `package` and `ldflags` build arguments, and comments that `package` can point at `./controlplane/kubeadm` or `./bootstrap/kubeadm` to build a narrower binary. That is the practical lever: the core providers are separate build targets from the main manager.

For local iteration the repository ships a `Tiltfile` and a `hack/` directory, and the `Makefile` pins the toolchain with `GO_VERSION ?= 1.26.10` while `go.mod` requires `go 1.26.0`. The Makefile also sets `KUBEBUILDER_ENVTEST_KUBERNETES_VERSION ?= 1.37.0` for controller tests, so running the controllers locally expects an envtest binary at that version.

Test infrastructure is part of the build, not an afterthought

A repository that ships its own end-to-end harness tells you something about the cost model. The `test/` directory and the `cloudbuild.yaml` and `cloudbuild-nightly.yaml` files ship in the repository alongside the code, with a separate configuration for nightly builds.

The dependency list in `go.mod` is the other tell. Alongside the usual controller-runtime dependencies sit `github.com/flatcar/container-linux-config-transpiler` and `github.com/flatcar/ignition`, which means the bootstrap path can render Flatcar Linux configuration, and `github.com/coredns/corefile-migration` alongside the etcd and apiserver client libraries. Careful version pinning is visible: the file carries an inline note that `github.com/google/cel-go` was bumped above the version pulled in by `k8s.io/apiserver` to address a CVE, with instructions to keep it at the minimum version that fixes the issue.

So the project is not a thin API library. It is a framework plus a test rig plus a supply chain that has to be rebuilt when a dependency advisory lands.

Where Cluster API is the wrong tool

For a single cluster, or for a handful of clusters that change twice a year, the overhead does not pay. Running Cluster API means running a management cluster that stores the desired state of every other cluster you own. That management cluster needs its own upgrades, its own backups and its own failure domain. You have converted a provisioning script into a production service.

There is a second boundary. If no provider exists for your infrastructure, the framework gives you CRDs and a reconciler and nothing else. The README names AWS, Azure and vSphere as examples, which means everything else is somebody's own project and your own integration work.

A third boundary is upgrade cadence across providers. Because the core CRDs and the provider CRDs must agree, adopting a very new core version means checking every provider in the management cluster. The README does not describe a compatibility window or a rollback procedure for a failed provider upgrade, so that check has to be done against the provider project rather than assumed.

What differs from Crossplane, Terraform and Kubespray

Terraform and Kubespray reach the same outcome by different means. Both run from a workstation or CI job and change infrastructure when you invoke them; the cluster exists while the command runs and nothing reconciles it afterwards. Cluster API keeps the desired state inside a running cluster and a controller acts on the difference, so the definition survives the machine that authored it.

Crossplane is the closer comparison because it is also a Kubernetes-native control loop over external resources. The distinction is scope and ownership: Crossplane models arbitrary cloud resources such as databases and buckets through composition, while Cluster API models the lifecycle of Kubernetes clusters themselves, with the Kubernetes shape baked into the resource design and kubeadm shipped as the bootstrap path.

If your need is one cluster on one cloud, a provider CLI plus a documented set of scripts is shorter and easier to debug. If your need is hundreds of clusters whose configuration must be reviewable in Git, that difference in approach is the whole argument.

exp/ features sit behind cluster gates, not build flags

The top-level entries split the code by stability, and that split is the clearest signal of upgrade cost. `exp/` and `feature/` sit beside `api/` and `controllers/` as separate top-level directories.

The project is not archived and its last push was on 2026-11-02, which says work is landing, not that your provider is keeping pace with it.

If you embed the API types in an internal tool, note that the repository is Apache-2.0, so the standard notice and patent grant apply. Confirm your provider projects carry compatible terms before you build a distribution around them.

Editorial conclusion

Adopt Cluster API if you run many clusters on infrastructure that already has a provider, if you want cluster definitions reviewable in Git, and if you can staff a management cluster plus a provider upgrade cadence. Do not adopt it for one or two clusters that change twice a year, and do not adopt it when no provider exists for your infrastructure, because the framework ships no cloud integration of its own. Experimental features live in exp/, so treat anything you enable there as upgrade-sensitive. Before anything else, check which provider build your chosen infrastructure publishes against the Cluster API version you plan to install.

Frequently asked questions

Official sources

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