Provisioning a Kubernetes Cluster on OpenStack Using Cluster API (CAPI)

Sri Sai Venkata Kasi Subbarayudu Kompella — Sun, 29 Mar 2026 13:24:25 +0000

This is my first blog post. I spent this weekend going deep into CAPI + CAPO + ORC. This guide covers everything - installation, configuration, manifests, and the full flow explained simply. If you want to understand CAPI, this guide is for you.

What Is Cluster API and Why Should You Care?

Managing Kubernetes clusters manually is painful. You manually create infrastructure, install Kubernetes packages, SSH into VMs, run kubeadm init, and then run kubeadm join to join the worker nodes, set up CNI, etc. Cluster API (CAPI) solves this by treating cluster creation as a Kubernetes-native, declarative operation. Cluster API is a Kubernetes project that lets you manage Kubernetes clusters using Kubernetes-style APIs.

Instead of running commands, you write YAML manifests and apply them to a "management cluster." CAPI controllers read those manifests and provision your cluster automatically — creating VMs, configuring networking, running kubeadm — all without you touching a single VM.

Three core concepts to understand:

Management Cluster — A small existing Kubernetes cluster that runs CAPI controllers and manages other clusters
Workload Cluster — The cluster CAPI creates for you, where your actual apps run
Providers — Plugins that tell CAPI how to talk to specific infrastructure (OpenStack, AWS, GCP, etc.)

Role of controllers:

CAPI installs multiple controllers.

Controller	Role
CAPI Core	Orchestrates cluster lifecycle — watches Cluster, Machine, MachineDeployment objects
CAPO (Cluster API Provider OpenStack)	Talks to OpenStack APIs — creates Nova VMs, Octavia LBs
CABPK (Kubeadm Bootstrap Provider)	Generates cloud-init scripts that run kubeadm on VMs
KCP (Kubeadm Control Plane Provider)	Manages control plane machine lifecycle and scaling

All are installed together via clusterctl.

If you have been reading about CAPO, you may have come across ORC — the OpenStack Resource Controller. ORC is a separate project and is not part of CAPO. It needs to be installed separately. ORC is a separate, optional Kubernetes controller that lets you manage OpenStack resources — Glance images, Nova keypairs, Neutron networks and routers — as Kubernetes custom resources, declaratively. The idea is that instead of manually uploading your node image to Glance and copying its UUID into your CAPI manifests, you declare an Image CRD in your management cluster, and ORC ensures it exists in OpenStack. It ensures the resources referenced in the CAPI manifest exist before creating the cluster.

Step 1 — Prerequisites

Before installing CAPI, you need:

A running management cluster (even a single-node kind or minikube cluster works)
clusterctl CLI installed
OpenStack credentials (your clouds.yaml file)
OpenStack environment with:
- At least one available flavor (e.g., m1.medium)
- A Glance image with Kubernetes pre-installed (qcow image with kubeadm/kubelet/kubectl pre-installed)
- A provider network created
- Octavia (Load Balancer service) enabled

Install clusterctl:

curl -L https://github.com/kubernetes-sigs/cluster-api/releases/latest/download/clusterctl-linux-amd64 \
  -o clusterctl
chmod +x clusterctl
sudo mv clusterctl /usr/local/bin/

Verify:

clusterctl version

Sample output:

clusterctl version: &version.Info{Major:"1", Minor:"12", GitVersion:"v1.12.3", GitCommit:"1a1852c74072febc3fbf9823c9dd32f4cd6cc747", GitTreeState:"clean", BuildDate:"2026-02-17T17:46:30Z", GoVersion:"go1.24.13", Compiler:"gc", Platform:"linux/amd64"}

Step 2 — Initialize CAPI with OpenStack Provider

clusterctl init --infrastructure openstack:v0.14.1

This installs:

CAPI core controllers
CAPO (OpenStack infrastructure provider)
CABPK (kubeadm bootstrap provider)
KCP (kubeadm control plane provider)

Sample Output:

Fetching providers
Installing cert-manager version="v1.19.3"
Waiting for cert-manager to be available...
spec.privateKey.rotationPolicy: In cert-manager >= v1.18.0, the default value changed from `Never` to `Always`.
Installing provider="cluster-api" version="v1.12.4" targetNamespace="capi-system"
spec.privateKey.rotationPolicy: In cert-manager >= v1.18.0, the default value changed from `Never` to `Always`.
Installing provider="bootstrap-kubeadm" version="v1.12.4" targetNamespace="capi-kubeadm-bootstrap-system"
spec.privateKey.rotationPolicy: In cert-manager >= v1.18.0, the default value changed from `Never` to `Always`.
Installing provider="control-plane-kubeadm" version="v1.12.4" targetNamespace="capi-kubeadm-control-plane-system"
spec.privateKey.rotationPolicy: In cert-manager >= v1.18.0, the default value changed from `Never` to `Always`.
Installing provider="infrastructure-openstack" version="v0.14.1" targetNamespace="capo-system"
spec.privateKey.rotationPolicy: In cert-manager >= v1.18.0, the default value changed from `Never` to `Always`.
Your management cluster has been initialized successfully!

You can now create your first workload cluster by running the following:

  clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f -

Verify all controllers are running:

kubectl get pods -A | grep -E "capi|capo|cert-manager"
capi-kubeadm-bootstrap-system       capi-kubeadm-bootstrap-controller-manager-5b6b785789-r62sl      1/1     Running   0          42m
capi-kubeadm-control-plane-system   capi-kubeadm-control-plane-controller-manager-95df764cf-hh7km   1/1     Running   0          42m
capi-system                         capi-controller-manager-6bbbfd79d8-b2dm4                        1/1     Running   0          42m
capo-system                         capo-controller-manager-6469cf765b-xhv8s                        1/1     Running   0          42m
cert-manager                        cert-manager-77f7698dcf-76hsq                                   1/1     Running   0          43m
cert-manager                        cert-manager-cainjector-557b97dd67-52fnw                        1/1     Running   0          43m
cert-manager                        cert-manager-webhook-5b7654ff4-cmgc8                            1/1     Running   0          43m

Step 3 — Set Environment Variables for Template Generation

clusterctl can generate cluster manifests from a template. You need to export these environment variables first:

export OPENSTACK_CLOUD=openstack # name should match the cloudname in clouds.yaml
export OPENSTACK_CLOUD_CACERT_B64=""
export  OPENSTACK_CLOUD_YAML_B64=$(base64 -w0 clouds.yaml) # get clouds.yaml from openstack horizon dashboard
export OPENSTACK_NODE_MACHINE_FLAVOR=m1.medium # instance type for ctrl plane node
export OPENSTACK_IMAGE_NAME=ubuntu-2404-kube # Name of the image used for kubernetes cluster.
export OPENSTACK_FAILURE_DOMAIN=nova  # avail zone usually nova.
export OPENSTACK_EXTERNAL_NETWORK_ID=5068d3a6-f560-4d79-b834-cd6943dc5de5 # ex: openstack network list | grep provider, get the id.
export OPENSTACK_DNS_NAMESERVERS=8.8.8.8
export OPENSTACK_SSH_KEY_NAME="kashi" # name of the SSH key uploaded in OpenStack and you want to be uploaded to cluster nodes

The image used in CAPI is prebuilt image that contains kubeadm, kubectl, kubelet all the kubernetes packages preinstalled.

You can build the image by running the following Makefile:

SHELL := /bin/bash

IMAGE_BUILDER_REPO=https://github.com/kubernetes-sigs/image-builder.git
IMAGE_BUILDER_DIR=image-builder

ifndef IMAGE_NAME
IMAGE_NAME=ubuntu-2404-kube-v1.34.3
$(warning IMAGE_NAME is undefined, using default: $(IMAGE_NAME))
endif

ifndef IMAGE_FILE
IMAGE_FILE=output/ubuntu-2404-kube-v1.34.3/ubuntu-2404-kube-v1.34.3
$(warning IMAGE_FILE is undefined, using default: $(IMAGE_FILE))
endif

OS_IMAGE_NAME=$(IMAGE_NAME)
OS_DISK_FORMAT=qcow2
OS_CONTAINER_FORMAT=bare
OS_VISIBILITY=public
ifndef ADMIN_RC_PATH
ADMIN_RC_PATH=/etc/kolla/admin-openrc.sh
$(warning ADMIN_RC_PATH is undefined, using default: $(ADMIN_RC_PATH))
endif


img-builder-clone:
    if [ ! -d "$(IMAGE_BUILDER_DIR)" ]; then \
        git clone $(IMAGE_BUILDER_REPO); \
    fi

capi-deps: img-builder-clone
    cd $(IMAGE_BUILDER_DIR)/images/capi && make deps-qemu


build-capi: capi-deps
    if [ ! -f "$(IMAGE_BUILDER_DIR)/images/capi/$(IMAGE_FILE)" ]; then \
       cd $(IMAGE_BUILDER_DIR)/images/capi && make build-qemu-ubuntu-2404 &> /dev/null; \
    fi


capi-upload: 
     . $(ADMIN_RC_PATH) && openstack image create $(OS_IMAGE_NAME) \
        --file $(IMAGE_BUILDER_DIR)/images/capi/$(IMAGE_FILE) \
        --disk-format $(OS_DISK_FORMAT) \
        --container-format $(OS_CONTAINER_FORMAT) \
        --public


capi-image: build-capi capi-upload

capi-delete:
     . $(ADMIN_RC_PATH) && openstack image delete $(OS_IMAGE_NAME)

all: capi-image

clean: 
    rm -rf $(IMAGE_BUILDER_DIR)  $(DISKIMAGE_DIR) $(OCTAVIA_REPO)

Run the makefile: make all

You can list the required environment variables to be set by running the following command:

clusterctl generate cluster --infrastructure openstack:v0.14.1 --list-variables capi-quickstart

Sample Output:

Required Variables:
  - KUBERNETES_VERSION
  - OPENSTACK_CLOUD
  - OPENSTACK_CLOUD_CACERT_B64
  - OPENSTACK_CLOUD_YAML_B64
  - OPENSTACK_CONTROL_PLANE_MACHINE_FLAVOR
  - OPENSTACK_DNS_NAMESERVERS
  - OPENSTACK_EXTERNAL_NETWORK_ID
  - OPENSTACK_FAILURE_DOMAIN
  - OPENSTACK_IMAGE_NAME
  - OPENSTACK_NODE_MACHINE_FLAVOR
  - OPENSTACK_SSH_KEY_NAME

Optional Variables:
  - CLUSTER_NAME                 (defaults to capi-quickstart)
  - CONTROL_PLANE_MACHINE_COUNT  (defaults to 1)
  - WORKER_MACHINE_COUNT         (defaults to 0)

Step 4 — Generate the Cluster Manifests

clusterctl generate cluster hind-cluster --infrastructure openstack:v0.14.1   --kubernetes-version v1.34.3  --control-plane-machine-count=1   --worker-machine-count=1  > capi-quickstart.yaml

The above command generates cluster manifests. Let's understand the generated manifests.

The Cluster manifest:

apiVersion: cluster.x-k8s.io/v1beta2
kind: Cluster
metadata:
  name: hind-cluster
  namespace: default
spec:
  clusterNetwork:
    pods:
      cidrBlocks:
      - 192.168.0.0/16
    serviceDomain: cluster.local
  controlPlaneRef:
    apiGroup: controlplane.cluster.x-k8s.io
    kind: KubeadmControlPlane
    name: hind-cluster-control-plane
  infrastructureRef:
    apiGroup: infrastructure.cluster.x-k8s.io
    kind: OpenStackCluster
    name: hind-cluster

This is the main object — it ties everything together. It says:

Pods get IPs from 192.168.0.0/16
Control plane is defined by KubeadmControlPlane
OpenStack infrastructure is defined by OpenStackCluster

The OpenStackCluster - OpenStack Infrastructure Definition

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OpenStackCluster
metadata:
  name: hind-cluster
  namespace: default
spec:
  apiServerLoadBalancer:
    enabled: true
  externalNetwork:
    id: c926f5e2-830e-43b0-9d06-89641bb8e131
  identityRef:
    cloudName: openstack
    name: hind-cluster-cloud-config
  managedSecurityGroups:
    allNodesSecurityGroupRules:
    - description: Created by cluster-api-provider-openstack - BGP (calico)
      direction: ingress
      etherType: IPv4
      name: BGP (Calico)
      portRangeMax: 179
      portRangeMin: 179
      protocol: tcp
      remoteManagedGroups:
      - controlplane
      - worker
    - description: Created by cluster-api-provider-openstack - IP-in-IP (calico)
      direction: ingress
      etherType: IPv4
      name: IP-in-IP (calico)
      protocol: "4"
      remoteManagedGroups:
      - controlplane
      - worker
  managedSubnets:
  - cidr: 10.6.0.0/24
    dnsNameservers:
    - 8.8.8.8

CAPO controller in the capo-system namespace reads this manifest and:

Checks the existence of the external network using the ID provided in the above manifest, also creates an internal network for our cluster, subnet, a router, and attaches this internal network to the router so the nodes in the cluster get internet access (outbound) and a security group that allows only the load balancer to access the backend cluster nodes. The client should be able to access the cluster only through the loadbalancer IP and the backend control plane IPs, or their identities are not exposed.
Creates security groups for the control plane and workers.
Creates an Octavia LoadBalancer for the Kubernetes API endpoint. This is especially useful when u have multiple control plane nodes, and the load balancer will load balance the requests across the control planes.
Sets the LB IP as the cluster's controlPlaneEndpoint

The kubeadmControlPlane definition:

apiVersion: controlplane.cluster.x-k8s.io/v1beta2
kind: KubeadmControlPlane
metadata:
  name: hind-cluster-control-plane
  namespace: default
spec:
  kubeadmConfigSpec:
    clusterConfiguration:
      controllerManager:
        extraArgs:
        - name: cloud-provider
          value: external
    initConfiguration:
      nodeRegistration:
        kubeletExtraArgs:
        - name: cloud-provider
          value: external
        - name: provider-id
          value: openstack:///'{{ instance_id }}'
        name: '{{ local_hostname }}'
    joinConfiguration:
      nodeRegistration:
        kubeletExtraArgs:
        - name: cloud-provider
          value: external
        - name: provider-id
          value: openstack:///'{{ instance_id }}'
        name: '{{ local_hostname }}'
  machineTemplate:
    spec:
      infrastructureRef:
        apiGroup: infrastructure.cluster.x-k8s.io
        kind: OpenStackMachineTemplate
        name: hind-cluster-control-plane
  replicas: 1
  version: v1.34.3

cloud-provider: external on kubelet: When kubelet starts, it adds a taint node.cloudprovider.kubernetes.io/uninitialized on the node. No pods schedule here until the OpenStack Cloud Controller Manager (CCM) initializes the node and removes this taint. This flag tells kubelet, "don't try to handle cloud stuff yourself, wait for external CCM."

cloud-provider: external on controller-manager - Disables the built-in cloud loops in kube-controller-manager (node lifecycle, service LoadBalancer, routes). These are handed off to the OpenStack CCM pod. When a load-balancer type service is created, it is the responsibility of the CCM to create an LB for you behind the scenes.

provider-id: openstack:///{{ instance_id }} - A unique ID linking the Kubernetes Node object to the actual Nova VM. {{ instance_id }} is a cloud-init template variable resolved to the real VM UUID at boot time. The OpenStack CCM uses this to fetch instance metadata.

The OpenStackMachineTemplate for Control Plane:

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OpenStackMachineTemplate
metadata:
  name: hind-cluster-md-0
  namespace: default
spec:
  template:
    spec:
      flavor: m1.medium
      image:
        filter:
          name: ubuntu-2404-kube
      sshKeyName: kashi

This tells CAPO what Nova flavor and Glance image to use for control plane VMs. The CAPO looks up the image in Glance and creates the VMs using the image UID fetched from Glance.

The MachineDeployment — Worker Node Pool

apiVersion: cluster.x-k8s.io/v1beta2
kind: MachineDeployment
metadata:
  name: hind-cluster-md-0
  namespace: default
spec:
  clusterName: hind-cluster
  replicas: 1
  selector:
    matchLabels: null
  template:
    spec:
      bootstrap:
        configRef:
          apiGroup: bootstrap.cluster.x-k8s.io
          kind: KubeadmConfigTemplate
          name: hind-cluster-md-0
      clusterName: hind-cluster
      failureDomain: nova
      infrastructureRef:
        apiGroup: infrastructure.cluster.x-k8s.io
        kind: OpenStackMachineTemplate
        name: hind-cluster-md-0
      version: v1.34.3

Like a Deployment for VMs. It ensures the desired number of worker nodes exists. It references KubeadmConfigTemplate for the cloud-init script and OpenStackMachineTemplate for VM specs.

The KubeadmConfigTemplate — Worker Bootstrap Config

apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
kind: KubeadmConfigTemplate
metadata:
  name: hind-cluster-md-0
  namespace: default
spec:
  template:
    spec:
      joinConfiguration:
        nodeRegistration:
          kubeletExtraArgs:
          - name: cloud-provider
            value: external
          - name: provider-id
            value: openstack:///'{{ instance_id }}'
          name: '{{ local_hostname }}'

Workers only have joinConfiguration — they never run kubeadm init, only kubeadm join. The same cloud-provider: external and provider-id flags are set here for the same reasons as the control plane.

So, when you apply capi-quickstart.yaml, CAPI sees the cluster object, and CAPO sees the OpenstackCluster object and creates the internal network, subnet, router, attaches subnet to the router for internet access ( router will have a port from the provider network as external gw ). It also creates security groups and the loadbalancer for kubernetes API server endpoint.

You should see the below events once when you describe the OpenstackCluster resource:

Events:
  Type    Reason                         Age   From                  Message
  ----    ------                         ----  ----                  -------
  Normal  Successfulcreatenetwork        54m   openstack-controller  Created network k8s-clusterapi-cluster-default-hind-cluster with id 05371ddd-a37e-43d6-ba6d-58599c4d2b7b
  Normal  Successfulcreatesubnet         54m   openstack-controller  Created subnet k8s-clusterapi-cluster-default-hind-cluster with id ea8186bc-88f7-4cc6-aa27-bf9b5a1154c5
  Normal  Successfulcreaterouter         54m   openstack-controller  Created router k8s-clusterapi-cluster-default-hind-cluster with id 8790e4f0-3b55-4d4e-acf4-8ce37e5719f4
  Normal  Successfulcreatesecuritygroup  54m   openstack-controller  Created security group k8s-cluster-default-hind-cluster-secgroup-controlplane with id e08613ca-135c-4f64-ba67-def6a1ffd7e1
  Normal  Successfulcreatesecuritygroup  54m   openstack-controller  Created security group k8s-cluster-default-hind-cluster-secgroup-worker with id 4ed61b8a-a9b0-4fb8-a3db-af6e457aea8a
  Normal  Successfulcreateloadbalancer   54m   openstack-controller  Created load balancer k8s-clusterapi-cluster-default-hind-cluster-kubeapi with id 421cd8a9-a7ba-4f41-8f03-1cdc4d958358
  Normal  Successfulcreatefloatingip     52m   openstack-controller  Created floating IP 10.31.0.101 with id 433d5f18-34dc-489d-b2ae-19ba2a167f8b
  Normal  Successfulassociatefloatingip  52m   openstack-controller  Associated floating IP 10.31.0.101 with port 6f0f82d9-bc8e-42e1-88eb-65ec33469d6e
  Normal  Successfulcreatelistener       52m   openstack-controller  Created listener k8s-clusterapi-cluster-default-hind-cluster-kubeapi-6443 with id c66b31a9-f9ee-4bfd-b61f-b402c266a8bf
  Normal  Successfulcreatepool           52m   openstack-controller  Created pool k8s-clusterapi-cluster-default-hind-cluster-kubeapi-6443 with id 465f565c-3a84-4b4d-938b-c28dfcc009af
  Normal  Successfulcreatemonitor        52m   openstack-controller  Created monitor k8s-clusterapi-cluster-default-hind-cluster-kubeapi-6443 with id 1349252f-b42b-4393-bab3-9243ff9b282e

And Also verify the network, subnet, router, security groups in your openstack cluster:

(kolla-venv) root@control-1:~#  openstack network list
+--------------------------------------+---------------------------------------------+--------------------------------------+
| ID                                   | Name                                        | Subnets                              |
+--------------------------------------+---------------------------------------------+--------------------------------------+
| 05371ddd-a37e-43d6-ba6d-58599c4d2b7b | k8s-clusterapi-cluster-default-hind-cluster | ea8186bc-88f7-4cc6-aa27-bf9b5a1154c5 |
| 40c70b44-1c45-407f-b590-5c019814ef57 | trove-mgmt                                  | 22b30e5a-4cbb-422d-9e9b-6f0ee2736c46 |
| 75bba094-d69a-4060-a271-a5d529915f01 | private-net                                 | e2c43b43-2936-4839-b57c-8c955f44f913 |
| 7e72fa18-46b5-4bfb-96bf-5666df021dec | lb-mgmt-net                                 | 2183795b-8723-490f-aaa9-5bb49f2d9af1 |
| c926f5e2-830e-43b0-9d06-89641bb8e131 | provider                                    | 4073439c-176e-46b7-8f78-9e7debdfef02 |
+--------------------------------------+---------------------------------------------+--------------------------------------+
(kolla-venv) root@control-1:~#  openstack subnet list
 +--------------------------------------+---------------------------------------------+--------------------------------------+-----------------+
| ID                                   | Name                                        | Network                              | Subnet          |
+--------------------------------------+---------------------------------------------+--------------------------------------+-----------------+
| 2183795b-8723-490f-aaa9-5bb49f2d9af1 | lb-mgmt-subnet                              | 7e72fa18-46b5-4bfb-96bf-5666df021dec | 10.1.0.0/24     |
| 22b30e5a-4cbb-422d-9e9b-6f0ee2736c46 | trove-mgmt-subnet                           | 40c70b44-1c45-407f-b590-5c019814ef57 | 10.33.0.0/24    |
| 4073439c-176e-46b7-8f78-9e7debdfef02 | provider-subnet                             | c926f5e2-830e-43b0-9d06-89641bb8e131 | 10.31.0.0/24    |
| e2c43b43-2936-4839-b57c-8c955f44f913 | private-subnet                              | 75bba094-d69a-4060-a271-a5d529915f01 | 192.168.50.0/24 |
| ea8186bc-88f7-4cc6-aa27-bf9b5a1154c5 | k8s-clusterapi-cluster-default-hind-cluster | 05371ddd-a37e-43d6-ba6d-58599c4d2b7b | 10.6.0.0/24     |
+--------------------------------------+---------------------------------------------+--------------------------------------+-----------------+
(kolla-venv) root@control-1:~#  
(kolla-venv) root@control-1:~#  openstack router list 
+--------------------------------------+---------------------------------------------+--------+-------+----------------------------------+-------------+-------+
| ID                                   | Name                                        | Status | State | Project                          | Distributed | HA    |
+--------------------------------------+---------------------------------------------+--------+-------+----------------------------------+-------------+-------+
| 40625a37-d00e-422c-a5b4-577c4d4c2a81 | trove-mgmt-router                           | ACTIVE | UP    | 2c2343fd2bd141e8a18229afefb9c4ff | False       | False |
| 8790e4f0-3b55-4d4e-acf4-8ce37e5719f4 | k8s-clusterapi-cluster-default-hind-cluster | ACTIVE | UP    | 2c2343fd2bd141e8a18229afefb9c4ff | False       | False |
+--------------------------------------+---------------------------------------------+--------+-------+----------------------------------+-------------+-------+
(kolla-venv) root@control-1:~# 
(kolla-venv) root@control-1:~# 
(kolla-venv) root@control-1:~# 
(kolla-venv) root@control-1:~#  openstack router show k8s-clusterapi-cluster-default-hind-cluster
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
| Field                   | Value                                                                                                                                                     |
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
| admin_state_up          | UP                                                                                                                                                        |
| availability_zone_hints |                                                                                                                                                           |
| availability_zones      | nova                                                                                                                                                      |
| created_at              | 2026-03-29T11:26:23Z                                                                                                                                      |
| description             | Created by cluster-api-provider-openstack cluster default-hind-cluster                                                                                    |
| distributed             | False                                                                                                                                                     |
| enable_ndp_proxy        | None                                                                                                                                                      |
| external_gateway_info   | {"network_id": "c926f5e2-830e-43b0-9d06-89641bb8e131", "external_fixed_ips": [{"subnet_id": "4073439c-176e-46b7-8f78-9e7debdfef02", "ip_address":         |
|                         | "10.31.0.246"}], "enable_snat": true}                                                                                                                     |
| flavor_id               | None                                                                                                                                                      |
| ha                      | False                                                                                                                                                     |
| id                      | 8790e4f0-3b55-4d4e-acf4-8ce37e5719f4                                                                                                                      |
| interfaces_info         | [{"port_id": "1e65d210-c1e7-4118-a847-d27b9058077b", "ip_address": "10.6.0.1", "subnet_id": "ea8186bc-88f7-4cc6-aa27-bf9b5a1154c5"}]                      |
| name                    | k8s-clusterapi-cluster-default-hind-cluster                                                                                                               |
| project_id              | 2c2343fd2bd141e8a18229afefb9c4ff                                                                                                                          |
| revision_number         | 3                                                                                                                                                         |
| routes                  |                                                                                                                                                           |
| status                  | ACTIVE                                                                                                                                                    |
| tags                    |                                                                                                                                                           |
| updated_at              | 2026-03-29T11:26:25Z                                                                                                                                      |
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
(kolla-venv) root@control-1:~# 
(kolla-venv) root@control-1:~# 
(kolla-venv) root@control-1:~# 
(kolla-venv) root@control-1:~#  openstack loadbalancer list
 +-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+
| id                                  | name                                | project_id                       | vip_address | provisioning_status | operating_status | provider |
+-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+
| 421cd8a9-a7ba-4f41-8f03-            | k8s-clusterapi-cluster-default-     | 2c2343fd2bd141e8a18229afefb9c4ff | 10.6.0.107  | ACTIVE              | ONLINE           | amphora  |
| 1cdc4d958358                        | hind-cluster-kubeapi                |                                  |             |                     |                  |          |
+-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+
(kolla-venv) root@control-1:~#  
(kolla-venv) root@control-1:~#  openstack  security group list
+--------------------------------------+--------------------------------------------------------+---------------------------+----------------------------------+------+--------+
| ID                                   | Name                                                   | Description               | Project                          | Tags | Shared |
+--------------------------------------+--------------------------------------------------------+---------------------------+----------------------------------+------+--------+
| 188e18b6-cc7e-42d6-8b56-a03cb9af5e5a | lb-421cd8a9-a7ba-4f41-8f03-1cdc4d958358                |                           | f37717d8ea254fdfb12bff38e8834f9d | []   | False  |
| 266e525f-2e15-4f72-9c11-7448c47d9abf | trove-sec-grp                                          | trove-sec-grp             | 2c2343fd2bd141e8a18229afefb9c4ff | []   | False  |
| 3a9617cd-6e92-4c7f-bad5-fd3dfb1996ed | default                                                | Default security group    | 2c2343fd2bd141e8a18229afefb9c4ff | []   | False  |
| 429b9c68-e2db-437c-b4db-bf7f8bad6d60 | default                                                | Default security group    | f37717d8ea254fdfb12bff38e8834f9d | []   | False  |
| 4ed61b8a-a9b0-4fb8-a3db-af6e457aea8a | k8s-cluster-default-hind-cluster-secgroup-worker       | Cluster API managed group | 2c2343fd2bd141e8a18229afefb9c4ff | []   | False  |
| 64ad5172-e754-416b-a228-b1bd9d98e96a | test                                                   | test                      | 2c2343fd2bd141e8a18229afefb9c4ff | []   | False  |
| 80fbc123-07f5-4b7d-bc2c-92891fc96668 | lb-mgmt-sec-grp                                        |                           | f37717d8ea254fdfb12bff38e8834f9d | []   | False  |
| e08613ca-135c-4f64-ba67-def6a1ffd7e1 | k8s-cluster-default-hind-cluster-secgroup-controlplane | Cluster API managed group | 2c2343fd2bd141e8a18229afefb9c4ff | []   | False  |
| e8fc39aa-668a-404a-afe0-98ffa118f4a1 | lb-health-mgr-sec-grp                                  |                           | f37717d8ea254fdfb12bff38e8834f9d | []   | False  |
+--------------------------------------+--------------------------------------------------------+---------------------------+----------------------------------+------+--------+
(kolla-venv) root@control-1:~#

As you can see, the resources created by the clusterAPI are prefixed with k8s-clusterapi, and security groups are prefixed with k8s-cluster.

Also, you can see that a load balancer has been created that will act as the frontend for our control plane nodes.

Then the capi-kubeadm-control-plane-controller-manager will see the KubeadmControlPlane object and create the kubeadmconfig and machine objects in the cluster.

Verify:

kubectl get kubeadmconfig

Output:

NAME                               CLUSTER        DATA SECRET CREATED   AGE
hind-cluster-control-plane-wggsv   hind-cluster   true                  57m
hind-cluster-md-0-xg7gb-qjlvj      hind-cluster   true                  57m

We see 2 objects, one for controlplane and the other for the worker node.

kubectl get machine

Output:

NAME                               CLUSTER        NODE NAME                          READY     AVAILABLE   UP-TO-DATE   PHASE     AGE   VERSION
hind-cluster-control-plane-wggsv   hind-cluster   hind-cluster-control-plane-wggsv   Unknown   False       True         Running   57m   v1.34.3
hind-cluster-md-0-xg7gb-qjlvj      hind-cluster   hind-cluster-md-0-xg7gb-qjlvj      True      True        True         Running   57m   v1.34.3

And capi-kubeadm-bootstrap-controller-manager, does a crucial job. It generates the cloud-init script that contains the actual kubeadm commands to be run during the booting process of our nodes in the cluster. This cloud-init script is actually stored in a secret.

Highlighted above are the secrets created by the controller that contain the cloud-init script. These secrets will be referenced by the machine objects created by kubeadm-controlplane-mgr.

kubectl get machine hind-cluster-control-plane-wggsv -o yaml
apiVersion: cluster.x-k8s.io/v1beta2
kind: Machine
metadata:
  annotations:
    pre-terminate.delete.hook.machine.cluster.x-k8s.io/kcp-cleanup: ""
  creationTimestamp: "2026-03-29T11:28:04Z"
  finalizers:
  - machine.cluster.x-k8s.io
  generation: 3
  labels:
    cluster.x-k8s.io/cluster-name: hind-cluster
    cluster.x-k8s.io/control-plane: ""
    cluster.x-k8s.io/control-plane-name: hind-cluster-control-plane
  name: hind-cluster-control-plane-wggsv
  namespace: default
  ownerReferences:
  - apiVersion: controlplane.cluster.x-k8s.io/v1beta2
    blockOwnerDeletion: true
    controller: true
    kind: KubeadmControlPlane
    name: hind-cluster-control-plane
    uid: d25ecc23-dd2c-417a-b891-f88eb85225af
  resourceVersion: "15813"
  uid: 4b4725ad-f1ee-4232-8c06-4cd2f14ed025
spec:
  bootstrap:
    configRef:
      apiGroup: bootstrap.cluster.x-k8s.io
      kind: KubeadmConfig
      name: hind-cluster-control-plane-wggsv
    dataSecretName: hind-cluster-control-plane-wggsv
  clusterName: hind-cluster
  deletion:
    nodeDeletionTimeoutSeconds: 10
  failureDomain: nova
  infrastructureRef:
    apiGroup: infrastructure.cluster.x-k8s.io
    kind: OpenStackMachine
    name: hind-cluster-control-plane-wggsv
  providerID: openstack:///3570638e-3d1c-4ccb-b758-86321356ea0d
  readinessGates:
  - conditionType: APIServerPodHealthy
  - conditionType: ControllerManagerPodHealthy
  - conditionType: SchedulerPodHealthy
  - conditionType: EtcdPodHealthy
  - conditionType: EtcdMemberHealthy
  version: v1.34.3

Verify the data secretName above. The value matches one of the secrets listed in the output of the get secrets command.

CAPO controller sees the machine object and calls the NOVA service to create the VM.

Also, while kubeadmcontrolplane is used for control plane nodes, machinedeployment is used for worker nodes.

After you applied the clusterAPI, manifests, get the kubeconfig of the workload cluster using:

clusterctl get kubeconfig hind-cluster > hind-cluster.kubeconfig

Export the kubeconfig and verify the cluster status:

export KUBECONFIG=./hind-cluster.kubeconfig
kubectl get nodes

Output:

NAME                               STATUS     ROLES           AGE   VERSION
hind-cluster-control-plane-wggsv   NotReady   control-plane   13m   v1.34.3
hind-cluster-md-0-xg7gb-qjlvj      NotReady   <none>          11m   v1.34.3

The nodes are in NotReady state. And it is completely expected. Because we need to install CNI.

You can install the CNI of your choice, I am going with calico:

kubectl --kubeconfig=./hind-cluster.kubeconfig \
  apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml

After installing the CNI, nodes should transition to Ready state:

kubectl get nodes
NAME                               STATUS   ROLES           AGE   VERSION
hind-cluster-control-plane-wggsv   Ready    control-plane   70m   v1.34.3
hind-cluster-md-0-xg7gb-qjlvj      Ready    <none>          68m   v1.34.3

Also, remember that we discussed about the role of openstack cloud controller manager above. In the above capi manifests, especially for kubeadmcontrolplane under kubeadmconfigspec, and in the kubeadmconfigtemplate of machine deployment. we specified extra args. i.e cloud-provider set to external.

Since these flags are set, the worker node and control plane node both will register themselves with a taint: node.cluster.x-k8s.io/uninitialized:NoSchedule.

So unless you install Openstack cloud controller manager the nodes will stay unschedulable. Let's verify this by logging into the nodes.
Verify the kubelet status on control plane node:

On worker node:

You notice the following flags on both the nodes.
On worker node:

/usr/bin/kubelet --bootstrap-kubeconfig=/etc/kubernetes/bootstrap-kubelet.conf --kubeconfig=/etc/kubernetes/kubelet.conf --config=/var/lib/kubelet/config.yaml --cloud-provider=external --pod-infra-container-image=registry.k8s.io/pause:3.10.1 --provider-id=openstack:///d9ae4dde-b281-421b-ad1b-36a2ee7db110 --register-with-taints=node.cluster.x-k8s.io/uninitialized:NoSchedule

The provider ID here corresponds to nova VM UUID. This is how OpenStack Cloud Controller Manager maps the Kubernetes node to nova vm object in OpenStack. Also, the cloud-provider is set to external.

On control plane:

usr/bin/kubelet --bootstrap-kubeconfig=/etc/kubernetes/bootstrap-kubelet.conf --kubeconfig=/etc/kubernetes/kubelet.conf --config=/var/lib/kubelet/config.yaml --cloud-provider=external --pod-infra-container-image=registry.k8s.io/pause:3.10.1 --provider-id=openstack:///3570638e-3d1c-4ccb-b758-86321356ea0d

Now check the taints.
For control plane:

For worker node:

So, now let's deploy OpenStack Cloud Controller Manager. Run the following steps:

wget https://raw.githubusercontent.com/kubernetes-sigs/cluster-api-provider-openstack/master/templates/env.rc -O /tmp/env.rc
chmod +x /tmp/env.rc
echo "Removing old cloud.conf files..."
rm -f /tmp/cloud.conf*
echo "Generating cloud.conf file from clouds.yaml..."
/tmp/env.rc ./clouds.yaml openstack
cp /tmp/cloud.conf* ./cloud.conf
echo "Creating secret in the kube-system ns..."
kubectl --kubeconfig=./hind-cluster.kubeconfig -n kube-system create secret generic cloud-config --from-file=cloud.conf
echo "Deploying cloud controller in the workload cluster..."
kubectl apply --kubeconfig=./hind-cluster.kubeconfig -f https://raw.githubusercontent.com/kubernetes/cloud-provider-openstack/master/manifests/controller-manager/cloud-controller-manager-roles.yaml
kubectl apply --kubeconfig=./hind-cluster.kubeconfig -f https://raw.githubusercontent.com/kubernetes/cloud-provider-openstack/master/manifests/controller-manager/cloud-controller-manager-role-bindings.yaml
kubectl apply --kubeconfig=./hind-cluster.kubeconfig -f https://raw.githubusercontent.com/kubernetes/cloud-provider-openstack/master/manifests/controller-manager/openstack-cloud-controller-manager-ds.yaml

tmp.rc is the script used to generate cloud.conf file from clouds.yaml. Download the clouds.yaml file from your OpenStack cloud and specify the path to this script as the first argument. And the second argument is the cloud name in the clouds.yaml.

Once you install the cloud controller manager, it will remove the taint, and you should see the coredns pods move to the running state from pending.

Create a workload and Test the cluster:

Now lets create a small nginx pod and then expose it using Loadbalancer service. We will see if the openstack CCM creates an LB or not.

root@hind-cluster-control-plane-wggsv:~# kubectl create deploy nginx --image=nginx
deployment.apps/nginx created
root@hind-cluster-control-plane-wggsv:~# 
root@hind-cluster-control-plane-wggsv:~# 
root@hind-cluster-control-plane-wggsv:~# 
root@hind-cluster-control-plane-wggsv:~# 
root@hind-cluster-control-plane-wggsv:~# kubectl get pods
NAME                     READY   STATUS              RESTARTS   AGE
nginx-66686b6766-549cc   0/1     ContainerCreating   0          4s
root@hind-cluster-control-plane-wggsv:~# kubectl expose deploy nginx --type=LoadBalancer --port=80
service/nginx exposed
root@hind-cluster-control-plane-wggsv:~# 
root@hind-cluster-control-plane-wggsv:~# 
root@hind-cluster-control-plane-wggsv:~# 
root@hind-cluster-control-plane-wggsv:~# kubectl get svc
NAME         TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
kubernetes   ClusterIP      10.96.0.1       <none>        443/TCP        90m
nginx        LoadBalancer   10.99.239.196   <pending>     80:31426/TCP   4s
root@hind-cluster-control-plane-wggsv:~#

Initially, it will be in the pending state. Describe the service and verify:

root@hind-cluster-control-plane-wggsv:~# kubectl describe svc nginx 
Name:                     nginx
Namespace:                default
Labels:                   app=nginx
Annotations:              <none>
Selector:                 app=nginx
Type:                     LoadBalancer
IP Family Policy:         SingleStack
IP Families:              IPv4
IP:                       10.99.239.196
IPs:                      10.99.239.196
Port:                     <unset>  80/TCP
TargetPort:               80/TCP
NodePort:                 <unset>  31426/TCP
Endpoints:                192.168.69.193:80
Session Affinity:         None
External Traffic Policy:  Cluster
Internal Traffic Policy:  Cluster
Events:
  Type    Reason                Age   From                Message
  ----    ------                ----  ----                -------
  Normal  EnsuringLoadBalancer  12s   service-controller  Ensuring load balancer

Also verify in the openstack cluster:

(kolla-venv) root@control-1:~#  openstack loadbalancer list
  +-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+
| id                                  | name                                | project_id                       | vip_address | provisioning_status | operating_status | provider |
+-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+
| 421cd8a9-a7ba-4f41-8f03-            | k8s-clusterapi-cluster-default-     | 2c2343fd2bd141e8a18229afefb9c4ff | 10.6.0.107  | ACTIVE              | ONLINE           | amphora  |
| 1cdc4d958358                        | hind-cluster-kubeapi                |                                  |             |                     |                  |          |
| 5289ba7f-dc63-4db2-a6a4-            | kube_service_kubernetes_default_ngi | 2c2343fd2bd141e8a18229afefb9c4ff | 10.6.0.203  | PENDING_CREATE      | ONLINE           | amphora  |
| f72d2e86f33d                        | nx                                  |                                  |             |                     |                  |          |
+-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+

Finally after sometime, the status should change to active:

(kolla-venv) root@control-1:~#   openstack loadbalancer list
+-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+
| id                                  | name                                | project_id                       | vip_address | provisioning_status | operating_status | provider |
+-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+
| 421cd8a9-a7ba-4f41-8f03-            | k8s-clusterapi-cluster-default-     | 2c2343fd2bd141e8a18229afefb9c4ff | 10.6.0.107  | ACTIVE              | ONLINE           | amphora  |
| 1cdc4d958358                        | hind-cluster-kubeapi                |                                  |             |                     |                  |          |
| 5289ba7f-dc63-4db2-a6a4-            | kube_service_kubernetes_default_ngi | 2c2343fd2bd141e8a18229afefb9c4ff | 10.6.0.203  | ACTIVE              | ONLINE           | amphora  |
| f72d2e86f33d                        | nx                                  |                                  |             |                     |                  |          |
+-------------------------------------+-------------------------------------+----------------------------------+-------------+---------------------+------------------+----------+

And the status of the service should change as follows:

root@hind-cluster-control-plane-wggsv:~# kubectl describe svc nginx 
Name:                     nginx
Namespace:                default
Labels:                   app=nginx
Annotations:              loadbalancer.openstack.org/load-balancer-address: 10.31.0.48
                          loadbalancer.openstack.org/load-balancer-id: 5289ba7f-dc63-4db2-a6a4-f72d2e86f33d
Selector:                 app=nginx
Type:                     LoadBalancer
IP Family Policy:         SingleStack
IP Families:              IPv4
IP:                       10.99.239.196
IPs:                      10.99.239.196
LoadBalancer Ingress:     10.31.0.48 (VIP)
Port:                     <unset>  80/TCP
TargetPort:               80/TCP
NodePort:                 <unset>  31426/TCP
Endpoints:                192.168.69.193:80
Session Affinity:         None
External Traffic Policy:  Cluster
Internal Traffic Policy:  Cluster
Events:
  Type    Reason                Age                 From                Message
  ----    ------                ----                ----                -------
  Normal  EnsuringLoadBalancer  23s (x2 over 117s)  service-controller  Ensuring load balancer
  Normal  EnsuredLoadBalancer   23s (x2 over 23s)   service-controller  Ensured load balancer

root@hind-cluster-control-plane-wggsv:~# kubectl get svc
NAME         TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
kubernetes   ClusterIP      10.96.0.1       <none>        443/TCP        95m
nginx        LoadBalancer   10.99.239.196   10.31.0.48    80:31426/TCP   4m49s

you can see that the service got an IP from provider network. Let's verify it through curl:

root@hind-cluster-control-plane-wggsv:~# curl  10.31.0.48
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, nginx is successfully installed and working.
Further configuration is required for the web server, reverse proxy, 
API gateway, load balancer, content cache, or other features.</p>

<p>For online documentation and support please refer to
<a href="https://nginx.org/">nginx.org</a>.<br/>
To engage with the community please visit
<a href="https://community.nginx.org/">community.nginx.org</a>.<br/>
For enterprise grade support, professional services, additional 
security features and capabilities please refer to
<a href="https://f5.com/nginx">f5.com/nginx</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>
root@hind-cluster-control-plane-wggsv:~#

Now let's scale the pods to 2 replicas and see the loadbalancing in action.

root@hind-cluster-control-plane-wggsv:~# kubectl scale deploy nginx --replicas=2
deployment.apps/nginx scaled

# In the first replica:
root@nginx-66686b6766-549cc:/usr/share/nginx/html# echo "Replica-1" > index.html 
# In the second replica:
root@nginx-66686b6766-mgks5:/usr/share/nginx/html# echo "Replica-2" > index.html

Verify loadbalancing:

root@hind-cluster-control-plane-wggsv:~# curl  10.31.0.48
Replica-2
root@hind-cluster-control-plane-wggsv:~# curl  10.31.0.48
Replica-1
root@hind-cluster-control-plane-wggsv:~# curl  10.31.0.48
Replica-1
root@hind-cluster-control-plane-wggsv:~# curl  10.31.0.48
Replica-1
root@hind-cluster-control-plane-wggsv:~# curl  10.31.0.48
Replica-1
root@hind-cluster-control-plane-wggsv:~# curl  10.31.0.48
Replica-2
root@hind-cluster-control-plane-wggsv:~#

That's all for now. If you found this helpful or got stuck somewhere, drop a comment below. This stuff took me a long time to piece together — happy to help you shortcut that journey.

DEV Community: Sri Sai Venkata Kasi Subbarayudu Kompella

Provisioning a Kubernetes Cluster on OpenStack Using Cluster API (CAPI)

What Is Cluster API and Why Should You Care?

Three core concepts to understand:

Role of controllers:

Step 1 — Prerequisites

Step 2 — Initialize CAPI with OpenStack Provider

Step 3 — Set Environment Variables for Template Generation

Create a workload and Test the cluster: