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+), and clusterctl (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-management with the host Docker socket mounted into its control plane container.
  • Expected observation: kind creates the cluster and switches your kubectl context to kind-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-plane reports Ready.

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-manager for 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-manager installation followed by the four CAPI providers, concluding with Your 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 Provider custom resource.
  • Expected observation: Four providers (cluster-api, kubeadm bootstrap, kubeadm control-plane, and docker infrastructure) 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, and capd-controller-manager all show 1/1 ready 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.yaml is 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.14 development flavors, CAPD uses Dev* resources (DevCluster, DevMachineTemplate). Older DockerCluster and DockerMachineTemplate resources 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 Cluster transitions to Provisioned. Control plane and worker Machine objects appear and progress from Pending to Provisioned to Running.

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, and MachineDeployment with [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 and kubelet is 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, and DevMachineTemplate, confirming DockerMachine is 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.infrastructureRef to show which concrete provider resource backs the generic Machine.
  • 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 returns No 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