In Cluster API, what is a management cluster, and how does it create and upgrade workload Kubernetes clusters declaratively?

## Why a fleet needs a management plane Creating one cluster by hand with `kubeadm init` and `kubeadm join` works. Doing it for fifteen clusters, and then upgrading all fifteen every few months, does not scale. **Cluster API** (CAPI) is a SIG Cluster Lifecycle project that applies the Kubernetes model to clusters themselves: you write the desired cluster as objects, and controllers reconcile real infrastructure to match. The cluster where those objects and controllers live is the **management cluster**. The clusters it creates, which run your applications, are **workload clusters**. ## The object model | Object (API group) | What it describes | |---|---| | `Cluster` (`cluster.x-k8s.io`) | The cluster as a whole, with references to its control plane and infrastructure | | `KubeadmControlPlane` (`controlplane.cluster.x-k8s.io`) | Control-plane replica count, Kubernetes `version`, and the kubeadm configuration | | `MachineDeployment` | A group of worker machines, rolled out like a Deployment rolls out pods | | `MachineSet` / `Machine` | One revision of workers, and one node's machine | | Infrastructure machine objects | The provider-specific VM or bare-metal host behind each `Machine` | | `MachineHealthCheck` | Rules for replacing unhealthy machines (remediation) | | `ClusterClass` | A reusable template, so many clusters can be declared with only a few parameters | Providers are pluggable: - **Infrastructure providers** talk to a cloud, a virtualisation platform or bare metal. - **Bootstrap providers** produce the data a machine boots with. The kubeadm provider makes each machine run `kubeadm init` or `kubeadm join`. - **Control-plane providers** manage the control-plane machines as a group. ## Bootstrap and pivot A management cluster has to exist before it can create clusters, so the usual sequence is: 1. Start a temporary **bootstrap cluster** (often kind) and run `clusterctl init` to install the providers. 2. Declare the long-lived management cluster there and let CAPI create it. 3. Run `clusterctl init` on the new cluster, then `clusterctl move --to-kubeconfig ...` to **pivot**. The move pauses reconciliation on the source (`spec.paused` on each `Cluster`), copies the objects and their dependent Secrets, and resumes reconciliation on the target. 4. Delete the bootstrap cluster. The management cluster can now be **self-hosted**, managing its own machines. ```bash clusterctl init --infrastructure docker clusterctl generate cluster accrual-eu-2 --flavor development \ --kubernetes-version v1.37.0 \ --control-plane-machine-count 3 \ --worker-machine-count 38 > accrual-eu-2.yaml kubectl apply -f accrual-eu-2.yaml clusterctl describe cluster accrual-eu-2 clusterctl get kubeconfig accrual-eu-2 > accrual-eu-2.kubeconfig ``` ## Declarative upgrades To upgrade a workload cluster, you change the Kubernetes `version` on the `KubeadmControlPlane` and in the `MachineDeployment`'s machine template. By default CAPI treats machines as **immutable**: - It creates a control-plane machine at the new version, waits for it to join, and removes an old one, repeating until all are replaced. - The `MachineDeployment` then rolls its workers the same way, draining each old node before deleting it. The version-skew and ordering rules still apply (control plane first, one minor version at a time). CAPI automates the replacement but does not remove those rules. `clusterctl upgrade apply` is a different operation: it upgrades the **providers** installed in the management cluster, not the workload clusters. ## When the management cluster is gone Each workload cluster has its own control plane, so losing the management cluster does **not** stop workload clusters or their pods. What you lose: - Scaling or creating clusters and machine groups. - Declarative upgrades. - `MachineHealthCheck` remediation of failed nodes. - Access to the stored `<cluster-name>-kubeconfig` Secrets. This makes the management cluster a **tier-zero** system: run it highly available, back up its objects (`clusterctl move --to-directory` can export them), and keep it separate from workload traffic. ## Fleet shape One management cluster per environment or region is common. It limits blast radius without adding many more management planes. Delivering applications onto the workload clusters is a separate concern, usually handled by a GitOps controller.