Cluster API (CAPI) on Hetzner

Provision Kubernetes clusters using Cluster API with the Hetzner infrastructure provider (CAPH).

Prerequisites

• lok8s CLI installed
• A CAPI management cluster (or use lo to bootstrap one)
• clusterctl installed
• Hetzner Cloud API token exported as HCLOUD_TOKEN

Cluster configuration

Create a cluster.lok8s.yaml with kind: Capi:

apiVersion: cluster.lok8s.dev/v1beta1
kind: Capi
metadata:
  name: capi-cluster
spec:
  kubernetes:
    version: "v1.35.5"
  provider: hetzner
  hcloud:
    region: fsn1
    sshPublicKeyFile: "~/.ssh/id_ed25519.pub"
    network:
      cidr: "10.0.0.0/16"
  controlPlane:
    replicas: 3
    type: cx33
  workers:
    platform:
      replicas: 2
      type: cpx31

How CAPI provisioning works

When you run lo provision with kind: Capi, lok8s:

1. Generates CAPI Cluster and MachineDeployment manifests
2. Applies them to the management cluster
3. CAPH creates Hetzner Cloud servers
4. Kubeadm bootstraps Kubernetes on the nodes
5. The kubeconfig is extracted and saved locally

Provision

lo provision

Template structure

lok8s generates these CAPI resources from your config:

• Cluster — cluster-level settings (network, region)
• HetznerCluster — Hetzner-specific infrastructure
• KubeadmControlPlane — control plane machines
• MachineDeployment — worker node pools
• HetznerMachineTemplate — server type and image

Verify

# Check CAPI cluster status
kubectl get clusters -A

# Check workload cluster nodes
kubectl --kubeconfig=kubeconfig get nodes

When to use CAPI vs KubeOne

Aspect	KubeOne	CAPI
Management cluster	Not required	Required
Declarative lifecycle	Partial	Full
Multi-cluster	Manual	Native
Complexity	Lower	Higher

Use KubeOne for single clusters with simple requirements. Use CAPI for multi-cluster environments or GitOps-driven infrastructure.

Next steps

• GitHub Actions — automate CAPI provisioning in CI
• Registration — register with the kubehz dashboard
• KubeOne — simpler alternative provisioner

---

Doc status

Aspect	Detail
State	active
Last reviewed	2026-07-10