Einführung
Die Verwaltung von Kubernetes-Clustern kann eine entmutigende Aufgabe sein, insbesondere im großen Maßstab. Die Cluster API (CAPI) ist ein offizielles Kubernetes SIG-Projekt, das die Bereitstellung, Upgrades und den Betrieb mehrerer Cluster auf deklarative Weise vereinfachen soll.
Dieser Ansatz bietet mehrere Vorteile gegenüber Infrastructure-as-Code-Tools, z.B. Terraform und Ansible, da er den gesamten Lebenszyklus deines Clusters verwaltet. Dazu gehören automatische Erstellung, Skalierung, Upgrades und Selbstheilung, im Gegensatz zu IaC-Tools, die einen vordefinierten Workflow auf Kommando ausführen.
Diese Vorteile lassen sich besser verstehen, wenn man die Tools im gleichen Szenario vergleicht: Wenn nach der anfänglichen Bereitstellung mit IaC-Tools versehentlich eine virtuelle Maschine oder ein Load Balancer gelöscht oder verändert wird, bleibt die Infrastruktur so lange kaputt, bis das nächste Mal eine Änderung vorgenommen oder bis der Fehler zufällig bemerkt wird (oder schlimmer noch, wenn Kunden anfangen, Probleme zu melden). Mit der Cluster API wird der Zustand des Clusters kontinuierlich mit dem gewünschten Zustand abgeglichen und Konfigurationsabweichungen automatisch korrigiert.
Der Cluster API Provider Hetzner (CAPH) ist ein Open-Source-Projekt (von Syself; nicht von Hetzner), das es ermöglicht, die Fähigkeiten der Cluster API zu nutzen, um hochverfügbare Kubernetes-Cluster sowohl auf Hetzner Baremetal-Servern (Robot) als auch auf Hetzner Cloud-Instanzen zu verwalten.
Dieses Tutorial behandelt den Prozess der Einrichtung eines hochverfügbaren Kubernetes-Clusters auf der Hetzner Cloud mit CAPH.
Voraussetzungen
- Docker, zum Ausführen von Containern
- Kind, zum Erstellen eines lokalen Kubernetes-Clusters
- kubectl und clusterctl, um auf die Cluster zuzugreifen und diese zu verwalten
- Ein "Hetzner Console"-Konto
- Ein SSH-Schlüssel
- Grundlegende Kenntnisse von Kubernetes
Schritt 1 - Vorbereiten des Hetzner-Kontos
Erstelle ein neues Projekt in der Hetzner Console, gehe auf den Reiter "Sicherheit" und erstelle einen API-Token mit Lese- und Schreibzugriff. Notiere diesen.
Wenn du noch keines hast, erstelle jetzt lokal ein SSH-Key-Paar. Füge den öffentlichen SSH-Schlüssel anschießend im Projekt hinzu, entweder über Hetzner Console oder über die hcloud-CLI:
export HCLOUD_TOKEN="<YOUR_HCLOUD_TOKEN>"
ssh-keygen -t ed25519 -f ~/.ssh/caph
hcloud ssh-key create \
--name caph-key \
--public-key-from-file ~/.ssh/caph.pubUm zu prüfen, ob der Key erfolgreich gespeichert wurde, führe hcloud ssh-key list aus. Der Output sollte caph-key enthalten.
Schritt 2 - Erstellen eines Management-Clusters
Ein Kubernetes-Cluster wird benötigt, um die Cluster API und die CAPH-Controller auszuführen. Er fungiert als Management-Cluster, mit dem der gesamte Lebenszyklus der Infrastruktur und Maschinen der Workload-Cluster mit Kubernetes-Objekten verwaltet werden können.
Wir beginnen mit einem lokalen Kind-Cluster, der als temporärer Bootstrap-Cluster dient. Später können wir die Controller auf dem neuen verwalteten Cluster in der Hetzner Cloud ausführen und unsere Ressourcen dorthin verschieben. Wenn du bereits einen laufenden Kubernetes-Cluster hast, kannst du diesen stattdessen verwenden.
Erstelle einen lokalen Kind-Cluster (Kubernetes in Docker):
# Erstelle einen Cluster mit Kind
kind create cluster --name caph-mgt-cluster
# Initialisiere ihn
clusterctl init --core cluster-api --bootstrap kubeadm --control-plane kubeadm --infrastructure hetznerBevor du das Workload-Cluster erstellst, warte bis cert-manager und alle Cluster-API-Provider Controller/Webhooks bereit sind:
# Warte bis jeder Befehl "condition met" zurück gibt.
kubectl wait --for=condition=Available deployment --all -n cert-manager --timeout=10m
kubectl wait --for=condition=Available deployment --all -n capi-system --timeout=10m
kubectl wait --for=condition=Available deployment --all -n capi-kubeadm-bootstrap-system --timeout=10m
kubectl wait --for=condition=Available deployment --all -n capi-kubeadm-control-plane-system --timeout=10m
kubectl wait --for=condition=Available deployment --all -n caph-system --timeout=10m
# Optional: Bestätige vorm Fortfahren, dass der CAPH-Webhook Endpunkte besitzt.
kubectl get endpointslices -n caph-systemErstelle jetzt im Management Cluster ein Secret, damit CAPH mit der Hetzner API kommunizieren kann:
# Verwende den in Schritt 1 exportierten Token
kubectl create secret generic hetzner --from-literal=hcloud="$HCLOUD_TOKEN"Schritt 3 - Erstelle dein Workload-Cluster
Definiere die folgenden Variablen. Der Wert von SSH_KEY_NAME sollte dem Namen des SSH-Keys aus Schritt 1 entsprechen (caph-key):
export SSH_KEY_NAME="caph-key"
export HCLOUD_REGION="hel1"
export CONTROL_PLANE_MACHINE_COUNT=3
export WORKER_MACHINE_COUNT=3
export KUBERNETES_VERSION=1.29.4
export HCLOUD_CONTROL_PLANE_MACHINE_TYPE=cpx32
export HCLOUD_WORKER_MACHINE_TYPE=cpx32Optional: Prüfe, welche Variablen die installierte Version benötigt:
clusterctl generate cluster hetzner-cluster --infrastructure hetzner --list-variablesUnd erstelle das Cluster:
# Generiere die Manifeste, die einen Workload-Cluster definieren, und erstelle sie im Bootstrap-Cluster
clusterctl generate cluster --infrastructure hetzner hetzner-cluster | kubectl apply -f -
# Optional: Prüfe den Fortschriff während das Workload-Cluster erstellt wird
clusterctl describe cluster hetzner-cluster
# Warte bis das Workload kubeconfig Secret erstellt ist (das kann mehrere Minuten dauern)
kubectl wait --for=create secret/hetzner-cluster-kubeconfig --timeout=30m
# Hole die kubeconfig für diesen neuen Cluster vom Kind-Management-Kontext
clusterctl get kubeconfig hetzner-cluster --kubeconfig ~/.kube/config --kubeconfig-context kind-caph-mgt-cluster > hetzner-cluster-kubeconfig.yamlJede Komponente und Konfiguration dieses Workload-Clusters kann deklarativ im Management-Cluster definiert werden. Wenn du den Befehl clusterctl generate erneut ausführst, siehst du die tatsächlichen Manifeste, die darauf angewendet wurden. Dies bedeutet, dass du Cluster nur durch Interaktion mit Kubernetes-Ressourcen skalieren, löschen und ändern kannst.
Bevor du den Cluster-API-Provider Hetzner in einem Produktionsszenario verwendest, solltest du die Dokumentationen CAPH und CAPI durchlesen und dich mit den wichtigsten Ressourcen vertraut machen, mit denen du interagieren wirst, wie z.B. Cluster, Machines, Machine Deployments, usw.
Aktuell ist es noch normal, dass die Workload-Nodes NotReady sind. Sie werden Ready, nachdem im nächsten Schritt eine CNI und die Hetzner CCM installiert wurden.
Nachdem das kubeconfig Secret erstellt wurde, dauert es noch mehrere Minuten, bis der Workload-API-Endpunkt und die Nodes erreichbar sind. Während dieser Zeit, geben API-Anfragen kurzzeitig EOF oder connection reset by peer zurück. Das bedeutet normalerweise, dass die Erstellung noch nicht abgeschlossen ist. Falls das passiert, warte einen Moment und versuche es erneut.
Schritt 4 - Installieren von Komponenten im Cluster
Der neu erstellte Cluster benötigt einige Schlüsselkomponenten, bevor Workloads darin laufen werden können. Dies sind ein Container Network Interface (CNI), das für die Netzwerkfunktionen zuständig ist, und ein Cloud Controller Manager (CCM), der es ermöglicht, Hetzner-Ressourcen, etwa Load Balancer, richtig zu nutzen.
export KUBECONFIG=hetzner-cluster-kubeconfig.yaml
# Hetzner CCM installieren
kubectl --kubeconfig=hetzner-cluster-kubeconfig.yaml apply -f https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm.yaml
# Flannel CNI installieren - du kannst stattdessen auch dein bevorzugtes CNI verwenden, z.B. Cilium
kubectl --kubeconfig=hetzner-cluster-kubeconfig.yaml apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.ymlBearbeite nun das Deployment hcloud-cloud-controller-manager:
kubectl--kubeconfig=hetzner-cluster-kubeconfig.yaml edit deployment hcloud-cloud-controller-manager -n kube-systemWechsle mit i in den "Insert-Modus". Suche nach HCLOUD_TOKEN und gebe für "key" den Wert hcloud an und für "name" den Wert hetzner:
- name: HCLOUD_TOKEN
valueFrom:
secretKeyRef:
key: hcloud
name: hetznerWenn du fertig bist, nutze esc, um den "Insert-Modus" zu verlassen und gebe :wq ein, um die Änderungen zu speichern und die Datei zu verlassen.
Das war's! Du hast nun einen funktionierenden Kubernetes-Cluster in der Hetzner Cloud.
kubectl --kubeconfig=hetzner-cluster-kubeconfig.yaml get nodesWenn du den Cluster löschen möchtest, kannst du den folgenden Befehl ausführen:
kubectl delete cluster hetzner-clusterDies löscht den Cluster und alle Ressourcen, die für ihn erstellt wurden, z.B. Maschinen.
Schritt 5 - Verschiebe den Management-Cluster auf den erstellten Cluster auf Hetzner (Optional)
Du kannst den neuen Cluster auf Hetzner als Management-Cluster verwenden und damit das temporäre Bootstrap-Cluster ersetzen.
Führe den Befehl clusterctl init aus, um CAPI- und CAPH-Controller im neuen Cluster einzusetzen:
KUBECONFIG=hetzner-cluster-kubeconfig.yaml clusterctl init --core cluster-api --bootstrap kubeadm --control-plane kubeadm --infrastructure hetznerUnd, zurück auf dem lokalen Art-Cluster, verwende clusterctl, um die Ressourcen zu verschieben:
# Dadurch wird das Geheimnis automatisch auf den Zielcluster verschoben
kubectl patch secret hetzner -p '{"metadata":{"labels":{"clusterctl.cluster.x-k8s.io/move":""}}}'
# Verschiebe die Cluster-Definitionen in den neuen Cluster. --namespace kann weggelassen werden, um den Standard zu verwenden
clusterctl move --to-kubeconfig=hetzner-cluster-kubeconfig.yaml --namespace=<target-namespace>Nach dem Verschieben kann der lokale Kind-Cluster sicher gelöscht werden:
kind delete cluster --name caph-mgt-clusterNächste Schritte
Der Workload-Cluster wurde mit den standardmäßigen kubeadm-Bootstrap- und Control-Plane-Providern erstellt. Für den produktiven Einsatz sollte dieser Konfiguration weitere Schichten hinzugefügt und etwa eigene Node-Images erstellt werden, da die Standardkonfiguration lediglich die Grundlagen für einen laufenden Cluster bietet.
Weitere Informationen darüber, welche Aspekte von CAPH behandelt werden, befinden sich im GitHub Readme des Projekts.
Baremetal
In der Einleitung zu diesem Artikel wurde erwähnt, dass CAPH die Verwendung von Hetzner Baremetal Servern (Hetzner Robot) vollständig unterstützt. Ein zweiter Leitfaden, der sich auf diese Funktion konzentriert, ist in Arbeit. Falls er noch nicht veröffentlicht wurde, wenn du diesen Artikel liest, kannst du die CAPH docs nutzen, wenn du an der Verwaltung von Hetzner Baremetal-Servern mit Cluster API interessiert bist.
Ergebnis
Mit dem Cluster-API-Provider Hetzner können hochverfügbare Kubernetes-Cluster in Hetzner erstellt und verwaltet werden, und zwar auf deklarative und Cloud-native Weise. Dies ermöglicht den nahtlosen Betrieb und Skalierung der Cluster. Ein einziger Cluster-API-Verwaltungscluster kann, je nach Anzahl der Knoten, etwa hundert Cluster verwalten.
In diesem Tutorial wurde ein hochverfügbarer Kubernetes-Cluster auf Hetzner erstellt, mit einem vollständig verwalteten Lebenszyklus. Wenn du weiter mit Kubernetes und dem Cluster-API-Provider Hetzner arbeiten möchtest, kannst du die zusätzlichen Funktionen und Konfigurationsoptionen erkunden, um das Cluster-Management zu optimieren, z.B.:
- Implementierung von benutzerdefinierten Node-Images und Konfigurationen, die auf deine spezifischen Workloads zugeschnitten sind
- Integration mit anderen Kubernetes-Tools und Add-ons wie CNI, Metrics-Server, Konnectivity, usw.
- Erhöhung der Zuverlässigkeit des Clusters durch Backups, Monitoring und Alarmierung