clusterctl manages and bootstraps the CAPI management environment; controllers manage workload-cluster lifecycle.
clusterctl
↓
setup / templates / provider lifecycle / inspection
CAPI controllers
↓
continuous reconciliation
clusterctl is a client-side CLI executed on demand. It does not run continuously, poll cloud APIs, or reconcile infrastructure drift. Once providers and manifests are written to Kubernetes, in-cluster controllers handle continuous reconciliation.
Here is the practical reference for the commands an engineer actually needs.
clusterctl init
What it does:
Transforms a Kubernetes cluster into a Cluster API management cluster. It installs CRDs, RBAC, and controller pods for the core provider (cluster-api), bootstrap provider (kubeadm), control plane provider (kubeadm), and specified infrastructure provider.
Example:
clusterctl init --infrastructure docker
Important caveat:clusterctl init is an imperative installer, not a declarative GitOps engine. It fetches release manifests from GitHub by default, requiring internet access or pre-mirrored container images for air-gapped environments (clusterctl init list-images).
Inspecting providers: kubectl get providers -A
To check installed provider versions on your management cluster:
kubectl get providers -A
Note:
clusterctl get providersdoes not exist. Installed provider inventory is tracked as standard Kubernetes custom resources (providers.clusterctl.cluster.x-k8s.io) and queried viakubectl.
To view upstream repositories that clusterctl queries when installing providers (rather than what is installed), briefly note:
clusterctl config repositories
clusterctl generate cluster
What it does:
Fetches a parameterized cluster template and substitutes environment variables and CLI flags to produce a complete workload cluster YAML manifest.
Example:
clusterctl generate cluster prod-cluster \
--kubernetes-version v1.31.0 \
--control-plane-machine-count=3 \
--worker-machine-count=3 > prod-cluster.yaml
Important caveat:
This command only renders text to stdout or a file—it does not create resources or validate cloud quotas. You must apply the generated file with kubectl apply -f prod-cluster.yaml. Missing required environment variables will cause generation to fail immediately.
clusterctl describe cluster
What it does:
Visualizes the management cluster’s object graph for a workload cluster, presenting a clean hierarchy of Cluster, KubeadmControlPlane, MachineDeployment, MachineSet, and Machine status conditions.
Example:
clusterctl describe cluster prod-cluster --disable-grouping
Important caveat:
By default, identical healthy worker machines are collapsed into a single summary line (3 Machines...). Pass --disable-grouping when troubleshooting to inspect every individual machine, and --disable-no-echo to display underlying infrastructure resources (DockerMachine, AWSMachine).
clusterctl get kubeconfig
What it does:
Extracts the administrative kubeconfig secret generated by Cluster API for a workload cluster.
Example:
clusterctl get kubeconfig prod-cluster > prod-cluster.kubeconfig
Important caveat:
The command fails if run before the workload cluster control plane finishes initializing and writes its <cluster-name>-kubeconfig secret to the management cluster.
clusterctl upgrade plan
What it does:
Scans installed Provider resources, compares them against upstream release metadata, and displays available upgrade targets and API contract compatibility.
Example:
clusterctl upgrade plan
Important caveat:clusterctl upgrade plan inspects only management plane provider controllers (core, bootstrap, control plane, infrastructure). It does not plan or check Kubernetes version upgrades for workload clusters, which are managed declaratively in cluster manifests.
clusterctl upgrade apply
What it does:
Executes an in-place upgrade of management plane provider controller deployments and CRDs.
Example:
clusterctl upgrade apply --contract v1beta1 --core capi-system/cluster-api:v1.14.0
Important caveat:
Upgrades must conform to supported CAPI API contracts (e.g., v1beta1). You cannot jump across incompatible API contracts without manual migration. Always verify compatibility with clusterctl upgrade plan first.
clusterctl move
clusterctl move transfers Cluster API management objects from one management cluster to another. It warrants closer attention because its operational role is distinct from ordinary cluster administration.
What it does:
Transfers ownership of all CAPI resources—Cluster, Machine, control plane objects, infrastructure resources, and associated credential secrets—from a source management cluster to a target management cluster without terminating or disrupting running workload nodes.
The common bootstrap/pivot use case:
When building a self-hosted or permanent production management cluster, you encounter a chicken-and-egg dilemma: you need a management cluster to provision the production cluster, but the production cluster does not exist yet.
The pivot pattern solves this:
- Spin up an ephemeral local cluster (e.g.,
kind). - Run
clusterctl initon the ephemeral cluster. - Deploy the target cluster as a workload cluster.
- Run
clusterctl initon the newly created target cluster. - Pivot ownership using
clusterctl move. - Terminate the ephemeral
kindcluster. The permanent cluster now manages itself and other workload clusters.
Example:
clusterctl move --to-kubeconfig target-management.kubeconfig
Important caveat: not a backup/restore mechanism:clusterctl move is designed exclusively for active management handoffs. It pauses reconciliation on the source cluster, copies the object graph, re-links owner references, unpauses on the target cluster, and removes objects from the source. It is not a snapshot or backup tool. Performing a move while workload modifications or rolling upgrades are in progress can lead to split-brain reconciliation or stranded cloud infrastructure.
Provider teardown: clusterctl delete
To uninstall provider controllers and CRDs from a management cluster:
clusterctl delete --infrastructure docker
Important caveat:clusterctl delete removes management plane controllers, not workload clusters. Workload VMs will remain running in your infrastructure provider unmanaged. To destroy a workload cluster, use kubectl delete cluster <name>.
Compact Reference Table
| Task | Command |
|---|---|
| Initialize management cluster | clusterctl init --infrastructure <provider> |
| Inspect installed providers | kubectl get providers -A |
| View upstream provider repositories | clusterctl config repositories |
| Render workload cluster manifest | clusterctl generate cluster <name> --kubernetes-version <ver> > <file>.yaml |
| Inspect cluster status tree | clusterctl describe cluster <name> --disable-grouping |
| Retrieve workload kubeconfig | clusterctl get kubeconfig <name> > <name>.kubeconfig |
| Check provider upgrade paths | clusterctl upgrade plan |
| Apply provider controller upgrades | clusterctl upgrade apply --contract <contract> ... |
| Pivot management state to another cluster | clusterctl move --to-kubeconfig <target.kubeconfig> |
| Remove provider from management cluster | clusterctl delete --infrastructure <provider> |
| Delete workload cluster infrastructure | kubectl delete cluster <name> |