Cluster API (CAPI) op Hetzner

Rol Kubernetes-clusters uit met Cluster API en de Hetzner-infrastructuurprovider (CAPH).

Eén cluster, eenvoudige vereisten? KubeOne is eenvoudiger: zie wanneer je welke gebruikt →

Vereisten

• lok8s CLI geïnstalleerd
• Een CAPI-managementcluster, of laat lo er met managementCluster.local: true in de spec een lokale kind-cluster van maken (zie de lok8s CAPI-gids). Hoe dan ook is managementCluster.domain verplicht: het benoemt de managementcluster, en local: true bepaalt alleen of lok8s hem aanmaakt in plaats van te verwachten dat hij al bestaat.
• clusterctl geïnstalleerd
• Hetzner Cloud API-token geëxporteerd als HCLOUD_TOKEN

Clusterconfiguratie

Maak clusters/example.com/cluster.lok8s.yaml aan met kind: Capi (de map is vernoemd naar je domein) en voer daarna lo use example.com uit. Anders dan KubeOne houdt de Capi-driver controlPlane en workers in de spec, omdat hij de CAPI-machineresources zelf genereert; het providerblok bevat alleen wat CAPH nodig heeft:

# clusters/example.com/cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: Capi
metadata:
  name: capi-cluster
spec:
  kubernetes:
    version: "v1.35.5"
  cluster:
    # VERPLICHT: een domein dat je beheert; voor het API-endpoint en certificaten
    domain: example.com
  managementCluster:
    # VERPLICHT voor self-hosted CAPI: `lo provision` start hier niet zonder
    domain: mgmt.example.com
    # Maak hem aan als lokale kind-cluster in plaats van een bestaande te verwachten
    local: true
  provider:
    name: hetzner
    config:
      # fsn1, nbg1 of hel1
      region: fsn1
      # een SSH-sleutel die in je Hetzner-project bestaat
      sshKeyName: my-key
      # standaardimage; Kubernetes wordt via cloud-init geïnstalleerd
      image: ubuntu-24.04
      network:
        # privé hcloud-netwerk
        enabled: true
      # spreid control plane + workers over hosts
      placementGroups: true
    credentials:
      envVars:
        - HCLOUD_TOKEN
      secretRef: capi-cluster-credentials
  controlPlane:
    # oneven aantal voor etcd-quorum
    replicas: 3
    type: cx33
  workers:
    platform:
      replicas: 2
      type: cpx31
  bootstrap:
    - cilium
    - ccm: {networking: {enabled: true}}

Hoe CAPI-provisioning werkt

Wanneer je lo provision uitvoert met kind: Capi, doet lok8s het volgende:

1. CAPI Cluster- en MachineDeployment-manifests genereren
2. Deze toepassen op het managementcluster
3. CAPH maakt Hetzner Cloud-servers aan
4. Kubeadm bootstrapt Kubernetes op de nodes
5. De kubeconfig van het workloadcluster wordt weggeschreven naar .kubeconfig/capi-cluster.yaml in je project, vernoemd naar metadata.name. Die van het managementcluster is .kubeconfig/mgmt.example.com.yaml, vernoemd naar managementCluster.domain. Je ~/.kube/config blijft ongemoeid.

Uitrollen

lo provision

De configuratie hierboven vraagt Hetzner om vijf servers (3 voor het control plane en 2 workers), die per uur worden gefactureerd tegen de gepubliceerde prijzen van Hetzner voor die servertypes. Niets hiervan is onomkeerbaar: lo destroy verwijdert wanneer je maar wilt elke server die lok8s heeft aangemaakt.

Templatestructuur

lok8s genereert deze CAPI-resources op basis van je configuratie:

• Cluster: instellingen op clusterniveau (netwerk, regio)
• HetznerCluster: Hetzner-specifieke infrastructuur
• KubeadmControlPlane: control plane-machines
• MachineDeployment: worker node-pools
• HetznerMachineTemplate: servertype en image

Verifiëren

CAPI-resources leven op het managementcluster, je nodes op het workloadcluster. Geen van beide is je standaard-kubectl-context, dus benoem elke kubeconfig expliciet:

# Status van het CAPI-cluster — op het managementcluster
kubectl --kubeconfig=.kubeconfig/mgmt.example.com.yaml get clusters -A

# Nodes van het workloadcluster
kubectl --kubeconfig=.kubeconfig/capi-cluster.yaml get nodes

Wanneer CAPI of KubeOne gebruiken

Aspect	KubeOne	CAPI
Managementcluster	Niet vereist	Vereist
Declaratieve levenscyclus	Gedeeltelijk	Volledig
Multi-cluster	Handmatig	Native
Complexiteit	Lager	Hoger

Gebruik KubeOne voor losse clusters met eenvoudige vereisten. Gebruik CAPI voor multi-cluster-omgevingen of GitOps-gestuurde infrastructuur.

Volgende stappen

• GitHub Actions: CAPI-provisioning automatiseren in CI
• Registratie: registreren bij het kubehz-dashboard
• KubeOne: eenvoudiger alternatieve provisioner

---

Documentstatus

Aspect	Detail
Status	active
Laatst herzien	2026-09-05