Cluster API on OpenStack: Part 3 - Deploying Workload Clusters

December 28, 2025

With a management cluster running and CAPI images in Glance, you’re ready to deploy workload clusters.

This is part 3 of the Cluster API on OpenStack series:

Introduction and Architecture
Building CAPI Images
Deploying Workload Clusters (this post)
Day-2 Operations

Creating a Workload Cluster

Generate a cluster manifest using clusterctl:

export OPENSTACK_EXTERNAL_NETWORK_ID=<your-external-network-uuid>
export OPENSTACK_IMAGE_NAME=ubuntu-2404-kube-v1.32.0
export OPENSTACK_SSH_KEY_NAME=<your-keypair-name>
export OPENSTACK_CONTROL_PLANE_MACHINE_FLAVOR=m1.medium-disk
export OPENSTACK_NODE_MACHINE_FLAVOR=m1.medium-disk
export OPENSTACK_DNS_NAMESERVERS=8.8.8.8

clusterctl generate cluster prod-cluster \
  --kubernetes-version v1.32.0 \
  --control-plane-machine-count=3 \
  --worker-machine-count=3 \
  > prod-cluster.yaml

Review and apply:

kubectl apply -f prod-cluster.yaml

Watch the cluster come up:

kubectl get cluster,machines,openstackmachines -w

Once the control plane is ready, retrieve the kubeconfig:

clusterctl get kubeconfig prod-cluster > prod-cluster.kubeconfig
kubectl --kubeconfig=prod-cluster.kubeconfig get nodes

Monitoring Cluster Health

CAPI resources have conditions that indicate their state:

# Cluster-level health
kubectl get cluster prod-cluster -o yaml | grep -A20 status:

# Machine-level details
kubectl get machines -o wide

# OpenStack-specific info
kubectl get openstackmachines -o yaml

Common issues to watch for:

Machines stuck in Provisioning - Check Nova quotas and CAPO controller logs
Control plane not initializing - Verify the image has kubeadm and the correct Kubernetes version
Load balancer issues - Ensure Octavia is configured if using master-lb-enabled

Troubleshooting

Check the CAPO controller logs for OpenStack-specific issues:

kubectl logs -n capo-system deployment/capo-controller-manager -f

For control plane issues, check the kubeadm bootstrap controller:

kubectl logs -n capi-kubeadm-bootstrap-system \
  deployment/capi-kubeadm-bootstrap-controller-manager -f

What’s Next

Once your cluster is running, you’ll need to perform day-2 operations like scaling workers and expanding disks.

Cluster API on OpenStack: Part 4 - Day-2 Operations Cluster API on OpenStack: Part 2 - Building CAPI Images