Cluster API (CAPI) auf Hetzner

Stelle Kubernetes-Cluster mit Cluster API und dem Hetzner-Infrastruktur-Provider (CAPH) bereit.

Ein einzelner Cluster, einfache Anforderungen? KubeOne ist einfacher: siehe, wann sich was eignet →

Voraussetzungen

lok8s CLI installiert
Ein CAPI-Management-Cluster, oder lass lo mit managementCluster.local: true in der Spec einen lokalen kind-Cluster anlegen (siehe den lok8s-CAPI-Leitfaden). In beiden Fällen ist managementCluster.domain erforderlich: Es benennt den Management-Cluster; local: true entscheidet nur, ob lok8s ihn anlegt, statt ihn vorauszusetzen.
clusterctl installiert
Hetzner-Cloud-API-Token als HCLOUD_TOKEN exportiert

Cluster-Konfiguration

Erstelle clusters/example.com/cluster.lok8s.yaml mit kind: Capi (der Ordner trägt den Namen deiner Domain) und führe dann lo use example.com aus. Anders als KubeOne behält der Capi-Treiber controlPlane und workers in der Spec, weil er die CAPI-Maschinenressourcen selbst erzeugt; der Provider-Block trägt nur, was CAPH braucht:

yaml

# clusters/example.com/cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: Capi
metadata:
  name: capi-cluster
spec:
  kubernetes:
    version: "v1.35.5"
  cluster:
    # PFLICHT: eine Domain, die dir gehört; für API-Endpunkt und Zertifikate
    domain: example.com
  managementCluster:
    # ERFORDERLICH für self-hosted CAPI: `lo provision` startet ohne dies nicht
    domain: mgmt.example.com
    # Als lokalen kind-Cluster anlegen, statt einen vorhandenen zu erwarten
    local: true
  provider:
    name: hetzner
    config:
      # fsn1, nbg1 oder hel1
      region: fsn1
      # ein SSH-Schlüssel, der in deinem Hetzner-Projekt existiert
      sshKeyName: my-key
      # Standard-Image; Kubernetes wird per cloud-init installiert
      image: ubuntu-24.04
      network:
        # privates hcloud-Netzwerk
        enabled: true
      # Control Plane + Worker über Hosts verteilen
      placementGroups: true
    credentials:
      envVars:
        - HCLOUD_TOKEN
      secretRef: capi-cluster-credentials
  controlPlane:
    # ungerade Zahl für das etcd-Quorum
    replicas: 3
    type: cx33
  workers:
    platform:
      replicas: 2
      type: cpx31
  bootstrap:
    - cilium
    - ccm: {networking: {enabled: true}}

So funktioniert die CAPI-Bereitstellung

Wenn du lo provision mit kind: Capi ausführst, führt lok8s folgende Schritte aus:

Generiert CAPI-Cluster- und MachineDeployment-Manifeste
Wendet sie auf den Management-Cluster an
CAPH erstellt Hetzner-Cloud-Server
Kubeadm bootstrappt Kubernetes auf den Nodes
Die Workload-kubeconfig wird als .kubeconfig/capi-cluster.yaml im Projekt abgelegt, benannt nach metadata.name. Die kubeconfig des Management-Clusters ist .kubeconfig/mgmt.example.com.yaml, benannt nach managementCluster.domain. Deine ~/.kube/config wird nicht angefasst.

Bereitstellen

bash

lo provision

Die Konfiguration oben fordert bei Hetzner fünf Server an (3 für die Control Plane und 2 Worker), die stündlich zu Hetzners veröffentlichten Preisen für diese Servertypen abgerechnet werden. Nichts davon ist endgültig: lo destroy entfernt jederzeit jeden Server, den lok8s angelegt hat.

Template-Struktur

lok8s generiert diese CAPI-Ressourcen aus deiner Konfiguration:

Cluster: Einstellungen auf Cluster-Ebene (Netzwerk, Region)
HetznerCluster: Hetzner-spezifische Infrastruktur
KubeadmControlPlane: Control-Plane-Maschinen
MachineDeployment: Worker-Node-Pools
HetznerMachineTemplate: Servertyp und Image

Überprüfen

CAPI-Ressourcen liegen auf dem Management-Cluster, deine Nodes auf dem Workload-Cluster. Keiner davon ist dein Standard-kubectl-Kontext, gib also jede kubeconfig explizit an:

bash

# CAPI-Cluster-Status — auf dem Management-Cluster
kubectl --kubeconfig=.kubeconfig/mgmt.example.com.yaml get clusters -A

# Nodes des Workload-Clusters
kubectl --kubeconfig=.kubeconfig/capi-cluster.yaml get nodes

Wann CAPI vs. KubeOne verwenden

Aspekt	KubeOne	CAPI
Management-Cluster	Nicht erforderlich	Erforderlich
Deklarativer Lebenszyklus	Teilweise	Vollständig
Multi-Cluster	Manuell	Nativ
Komplexität	Geringer	Höher

Verwende KubeOne für einzelne Cluster mit einfachen Anforderungen. Verwende CAPI für Multi-Cluster-Umgebungen oder GitOps-gesteuerte Infrastruktur.

Nächste Schritte

GitHub Actions: CAPI-Bereitstellung in CI automatisieren
Registrierung: beim kubehz-Dashboard registrieren
KubeOne: einfachere alternative Provisioner

Doku-Status

Aspekt	Detail
Zustand	aktiv
Zuletzt geprüft	2026-09-05

Cluster API (CAPI) auf Hetzner ​

Voraussetzungen ​

Cluster-Konfiguration ​

So funktioniert die CAPI-Bereitstellung ​

Bereitstellen ​

Template-Struktur ​

Überprüfen ​

Wann CAPI vs. KubeOne verwenden ​

Nächste Schritte ​

Doku-Status ​