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 providers does not exist. Installed provider inventory is tracked as standard Kubernetes custom resources (providers.clusterctl.cluster.x-k8s.io) and queried via kubectl.

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:

  1. Spin up an ephemeral local cluster (e.g., kind).
  2. Run clusterctl init on the ephemeral cluster.
  3. Deploy the target cluster as a workload cluster.
  4. Run clusterctl init on the newly created target cluster.
  5. Pivot ownership using clusterctl move.
  6. Terminate the ephemeral kind cluster. 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

TaskCommand
Initialize management clusterclusterctl init --infrastructure <provider>
Inspect installed providerskubectl get providers -A
View upstream provider repositoriesclusterctl config repositories
Render workload cluster manifestclusterctl generate cluster <name> --kubernetes-version <ver> > <file>.yaml
Inspect cluster status treeclusterctl describe cluster <name> --disable-grouping
Retrieve workload kubeconfigclusterctl get kubeconfig <name> > <name>.kubeconfig
Check provider upgrade pathsclusterctl upgrade plan
Apply provider controller upgradesclusterctl upgrade apply --contract <contract> ...
Pivot management state to another clusterclusterctl move --to-kubeconfig <target.kubeconfig>
Remove provider from management clusterclusterctl delete --infrastructure <provider>
Delete workload cluster infrastructurekubectl delete cluster <name>