Creating the workload cluster

Generate the cluster.yaml #

The clusterctl generate cluster command returns a YAML template for creating a workload cluster. It generates a YAML file named my-cluster.yaml with a predefined list of Cluster API objects (Cluster, Machines, MachineDeployments, etc.) to be deployed in the current namespace.

		clusterctl generate cluster my-cluster --kubernetes-version v1.36.0 --control-plane-machine-count=3 --worker-machine-count=3  > my-cluster.yaml
	

Apply the workload cluster #

The following command applies the configuration of the workload cluster:

		kubectl apply -f my-cluster.yaml
	

Access the workload cluster #

The cluster will now start provisioning. You can check status with:

		kubectl get cluster
	

You can also view the cluster and its resources at a glance by running:

		clusterctl describe cluster my-cluster
	

To verify the first control plane is up, use the following command:

		kubectl get kubeadmcontrolplane
	

Wait until the INITIALIZED column reports True before moving on. The READY column will stay False until we install a CNI in the next step — that is expected. If you'd like to follow the progression live, run kubectl get kubeadmcontrolplane -w.

Once initialized, retrieve the kubeconfig of the workload cluster:

		export CAPH_WORKER_CLUSTER_KUBECONFIG=/tmp/workload-kubeconfig
clusterctl get kubeconfig my-cluster > $CAPH_WORKER_CLUSTER_KUBECONFIG
	

A quick reachability check before installing the CNI:

		KUBECONFIG=$CAPH_WORKER_CLUSTER_KUBECONFIG kubectl get --raw='/readyz'
	

You should see ok (a few component-level failures are still acceptable at this stage). If the call hangs or returns an EOF, give it another minute and retry.

Deploy the CNI solution #

Cilium is used as a CNI solution in this guide. The values file lives in this repo at templates/cilium/values.yaml; we install it directly from the raw URL:

		helm repo add cilium https://helm.cilium.io/
 
KUBECONFIG=$CAPH_WORKER_CLUSTER_KUBECONFIG helm upgrade --install cilium cilium/cilium \
--namespace kube-system \
-f https://raw.githubusercontent.com/syself/cluster-api-provider-hetzner/main/templates/cilium/values.yaml
	

You can, of course, also install an alternative CNI, e.g., calico.

Deploy the Cloud Controller Manager (CCM) #

The CCM runs in the workload cluster and integrates Kubernetes with the Hetzner APIs. In practice, it is responsible for tasks such as setting the ProviderID on nodes and managing load balancers. You need to install a CCM in this flow so the workload cluster can properly interact with Hetzner infrastructure.

You have two options here:

• Syself CCM: the ccm-hetzner chart maintained by Syself.
• Hetzner CCM: the upstream hcloud-cloud-controller-manager from Hetzner Cloud.

Syself CCM#

CAPH already syncs the hcloud secret you created on the previous page into the workload cluster's kube-system namespace, so the CCM only needs to be pointed at it (the chart default is hetzner, so we override secret.name):

		helm repo add syself https://charts.syself.com
helm repo update syself
 
KUBECONFIG=$CAPH_WORKER_CLUSTER_KUBECONFIG helm upgrade --install ccm syself/ccm-hetzner \
  --version 2.0.6 \
  --namespace kube-system \
  --set secret.name=hcloud
	

Hetzner CCM (upstream)#

The upstream hcloud-cloud-controller-manager static manifest (deploy/ccm.yaml) is hardcoded to read the token from secret hcloud with key token. Even though the management secret you created on the previous page only has the key hcloud, CAPH's compatibility shim writes the workload-cluster copy with both keys (hcloud and token) — so the upstream manifest works as-is, no patching required:

		KUBECONFIG=$CAPH_WORKER_CLUSTER_KUBECONFIG kubectl apply \
  -f https://raw.githubusercontent.com/hetznercloud/hcloud-cloud-controller-manager/main/deploy/ccm.yaml
	

If you install the upstream CCM via its Helm chart instead, the defaults also point at secret hcloud / key token, so no --set overrides are needed.

For upstream CCM details and bare-metal ProviderID format, see the Baremetal Docs .

Deploy the CSI (optional) #

The Hetzner CSI chart lives in the hcloud Helm repo, which we add first. The chart's default controller.hcloudToken.existingSecret already points at secret hcloud with key token, which matches what CAPH wrote into the workload cluster — so no overrides are needed beyond the storage class definition:

		helm repo add hcloud https://charts.hetzner.cloud
helm repo update hcloud
 
cat << EOF > csi-values.yaml
storageClasses:
- name: hcloud-volumes
  defaultStorageClass: true
  reclaimPolicy: Retain
EOF
 
KUBECONFIG=$CAPH_WORKER_CLUSTER_KUBECONFIG helm upgrade --install csi hcloud/hcloud-csi \
--namespace kube-system -f csi-values.yaml
	

Clean up (optional) #

If you want to continue with the next step and move the Cluster API components to your workload cluster (so it becomes the new management cluster), do not run the cleanup command.

If you want to stop here, delete the workload cluster and remove all of the components by using:

		kubectl delete cluster my-cluster
	

Delete management cluster with the following command:

		kind delete cluster