You do not need a cloud account to get hands-on experience with Cluster API (CAPI). Using kind (Kubernetes in Docker) and the Docker infrastructure provider (CAPD), you can run a complete, multi-cluster management and workload setup on a single workstation in about 15 to 20 minutes.
This lab focuses strictly on practical execution and reproducible steps. These notes walk you through provisioning a local management cluster, deploying a workload cluster, watching resource expansion, and tearing everything down cleanly.
1. Prerequisites
Before starting, verify your workstation has Docker running with adequate capacity. CAPD executes each workload node as an independent container running systemd and containerd, so ensure Docker has at least 6 GB of RAM allocated.
Verify required client binaries:
docker version --format '{{.Server.Version}}'
kind version
kubectl version --client
clusterctl version
- Explanation: Confirms that
docker(v24+),kind(v0.20+),kubectl(v1.30+), andclusterctl(v1.14+) are installed in your PATH and the Docker daemon is accessible. - Expected observation: Version numbers printed for each utility without connection or permission errors.
2. Create kind management cluster
CAPD runs inside the management cluster and requires access to the host Docker daemon to launch workload node containers. To allow this, create a kind cluster that bind-mounts /var/run/docker.sock.
Create kind-cluster-with-extramounts.yaml:
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
ipFamily: dual
nodes:
- role: control-plane
extraMounts:
- hostPath: /var/run/docker.sock
containerPath: /var/run/docker.sock
Create the management cluster:
kind create cluster \
--name capi-management \
--config kind-cluster-with-extramounts.yaml
- Explanation: Provisions a local kind cluster named
capi-managementwith the host Docker socket mounted into its control plane container. - Expected observation:
kindcreates the cluster and switches your kubectl context tokind-capi-management.
Verify the node is ready:
kubectl get nodes
- Explanation: Confirms the management cluster control plane node is online.
- Expected observation:
capi-management-control-planereportsReady.
3. clusterctl init –infrastructure docker
Turn the plain kind cluster into a Cluster API management plane:
export CLUSTER_TOPOLOGY=true
clusterctl init --infrastructure docker
- Explanation: Enables cluster topology support, installs
cert-managerfor admission webhooks, registers all CAPI CRDs, and deploys controller managers for Core, Bootstrap, Control Plane, and Docker infrastructure providers. - Expected observation: Terminal logs show
cert-managerinstallation followed by the four CAPI providers, concluding withYour management cluster has been initialized successfully!.
4. Verify provider controllers
Do not guess CLI commands: clusterctl get providers does not exist. Inspect installed providers by querying the Kubernetes CRD directly.
Query registered providers:
kubectl get providers -A
- Explanation: Lists all installed CAPI provider components tracked by the
Providercustom resource. - Expected observation: Four providers (
cluster-api,kubeadmbootstrap,kubeadmcontrol-plane, anddockerinfrastructure) listed across their respective namespaces with matching versions.
Verify controller deployments:
kubectl get deployments -A | grep -E 'capi|capd|kubeadm'
- Explanation: Confirms the controller manager pods for all four provider domains are running.
- Expected observation: Deployments
capi-controller-manager,capi-kubeadm-bootstrap-controller-manager,capi-kubeadm-control-plane-controller-manager, andcapd-controller-managerall show1/1ready replicas.
5. Generate workload cluster YAML
Generate the declarative manifest for a local workload cluster:
clusterctl generate cluster capi-quickstart \
--flavor development \
--kubernetes-version v1.32.0 \
--control-plane-machine-count=1 \
--worker-machine-count=1 \
> capi-quickstart.yaml
- Explanation: Renders a complete client-side YAML template for a 2-node cluster (1 control plane, 1 worker) without touching the API server.
- Expected observation: The file
capi-quickstart.yamlis generated in your working directory.
Inspect the resource kinds defined in the file:
grep '^kind:' capi-quickstart.yaml
- Explanation: Displays the Custom Resource kinds included in the manifest.
- Expected observation:
kind: Cluster kind: DevCluster kind: KubeadmControlPlane kind: DevMachineTemplate kind: MachineDeployment kind: KubeadmConfigTemplate
Provider naming note: In current CAPI
v1.14development flavors, CAPD usesDev*resources (DevCluster,DevMachineTemplate). OlderDockerClusterandDockerMachineTemplateresources are deprecated.
6. Apply it
Submit the workload manifest to the management cluster:
kubectl apply -f capi-quickstart.yaml
- Explanation: Posts your high-level intent objects to the management API server, initiating asynchronous controller reconciliation loops.
- Expected observation: Output confirms creation of
Cluster,DevCluster,KubeadmControlPlane,MachineDeployment, and template objects.
7. Watch CAPI resources appear
Monitor the cluster as controllers expand the declarations into physical nodes.
CLI trap to avoid: Do not run multi-resource streaming watch like kubectl get cluster,machines -w. The kubectl CLI does not support streaming watch across multiple distinct resource types in one command. Use the terminal watch command instead:
watch -n 2 'kubectl get clusters,kubeadmcontrolplanes,machinedeployments,machines'
- Explanation: Polls top-level cluster definitions and derived machine objects every two seconds.
- Expected observation: The
Clustertransitions toProvisioned. Control plane and workerMachineobjects appear and progress fromPendingtoProvisionedtoRunning.
What you should see
Cluster API controllers automatically expand your submitted intent into this runtime hierarchy:
Cluster
├── KubeadmControlPlane
├── MachineDeployment
├── MachineSet
└── Machines
KubeadmControlPlane manages the control plane Machine directly. MachineDeployment creates an intermediate MachineSet, which stamps out the worker Machine.
Inspect this live hierarchy at any time using clusterctl:
clusterctl describe cluster capi-quickstart
- Explanation: Renders an ASCII tree of the cluster, showing control plane quorum, machine replicas, and provider status.
- Expected observation: A structured tree showing
Cluster,KubeadmControlPlane, andMachineDeploymentwith[Running]status across nodes.
8. Get workload kubeconfig
Extract the administrative credentials generated for the new cluster:
clusterctl get kubeconfig capi-quickstart > capi-quickstart.kubeconfig
- Explanation: Retrieves the admin kubeconfig Secret (
capi-quickstart-kubeconfig) created by CAPI controllers in the management cluster and writes it to a file. - Expected observation: A functional kubeconfig file written to
./capi-quickstart.kubeconfig.
9. Check Nodes
Query the workload cluster directly using the extracted kubeconfig:
kubectl --kubeconfig=./capi-quickstart.kubeconfig get nodes
- Explanation: Targets the workload cluster API server to inspect registered Kubernetes nodes.
- Expected observation:
NAME STATUS ROLES AGE VERSION capi-quickstart-control-plane-7h9k2 NotReady control-plane 3m40s v1.32.0 capi-quickstart-md-0-5b9k8 NotReady <none> 3m10s v1.32.0
Crucial observation: Machine Running vs Node Ready
Notice that both workload nodes report NotReady.
In the management cluster, kubectl get machines reports Running. Yet inside the workload cluster, kubectl get nodes reports NotReady.
- Machine
Running: Indicates the underlying infrastructure container has started andkubeletis executing. - Node
Ready: Indicates the node has passed health checks and established functioning pod networking.
A Machine in Running state does not mean the Kubernetes Node is Ready.
10. Install/mention CNI if Nodes remain NotReady
Cluster API intentionally decouples machine provisioning from workload networking. CAPI provisions hosts and bootstraps kubelet, but does not deploy a Container Network Interface (CNI). Without a CNI, CoreDNS cannot run and nodes stay NotReady with NetworkPluginNotReady.
Deploy Calico to the workload cluster:
kubectl --kubeconfig=./capi-quickstart.kubeconfig \
apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.0/manifests/calico.yaml
- Explanation: Installs Calico network daemonsets and CRDs directly into the workload cluster.
- Expected observation: Calico manifests are applied.
Watch nodes transition to ready:
kubectl --kubeconfig=./capi-quickstart.kubeconfig get nodes -w
- Explanation: Streams node status updates on the workload cluster until pod networking initializes.
- Expected observation: Within 60 to 90 seconds, both nodes transition to
Ready:NAME STATUS ROLES AGE VERSION capi-quickstart-control-plane-7h9k2 Ready control-plane 5m20s v1.32.0 capi-quickstart-md-0-5b9k8 Ready <none> 4m50s v1.32.0
11. Inspect one Machine and its infrastructureRef
Return to the management cluster to see how generic CAPI objects connect to Docker containers.
Discover registered infrastructure resources:
kubectl api-resources --api-group infrastructure.cluster.x-k8s.io
- Explanation: Identifies the concrete infrastructure CRDs registered in the management cluster.
- Expected observation: Lists
DevCluster,DevMachine, andDevMachineTemplate, confirmingDockerMachineis deprecated in v1.14 development flavor.
Find your worker machine name:
kubectl get machines -l cluster.x-k8s.io/deployment-name=capi-quickstart-md-0
- Explanation: Queries machines filtered by their parent
MachineDeployment. - Expected observation: Returns the worker machine name (e.g.
capi-quickstart-md-0-5b9k8).
Inspect its infrastructure reference:
kubectl get machine <name> \
-o jsonpath='{.spec.infrastructureRef.kind}{"\n"}'
- Explanation: Reads
.spec.infrastructureRefto show which concrete provider resource backs the genericMachine. - Expected observation: Prints
DevMachine.
Inspect the underlying containers on your host machine:
docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}"
- Explanation: Queries the host Docker daemon to inspect containers created by CAPD.
- Expected observation: Three running containers: the management cluster control plane, the workload control plane, and the workload worker node.
This verifies the lifecycle path: Machine → DevMachine → CAPD Controller → Docker container → Kubernetes Node.
12. Cleanup
Always delete resources in the correct sequence. Deleting the kind management cluster before deleting the workload cluster leaves orphaned containers running on your host Docker engine.
Delete the workload cluster:
kubectl delete cluster capi-quickstart
- Explanation: Triggers CAPI cascading deletion finalizers to safely drain nodes, remove containers, clean up Docker networks, and delete API objects.
- Expected observation: Monitor with
kubectl get clusters. Once the command returnsNo resources found, all workload containers are removed.
Delete the management cluster:
kind delete cluster --name capi-management
- Explanation: Deletes the local kind management cluster container and frees host resources.
- Expected observation: Output confirms
Deleted nodes: ["capi-management-control-plane"].
Clean up generated local files:
rm -f kind-cluster-with-extramounts.yaml capi-quickstart.yaml capi-quickstart.kubeconfig