Blog Hetzner – Cluster Creation with KubeOne

Einleitung

In unserem letzten Artikel haben wir die Hetzner Cloud als günstige, aber leistungsfähige Alternative zu großen Hyperscalern vorgestellt. Jetzt gehen wir einen Schritt weiter und zeigen, wie sich auf dieser Basis ein produktionsreifes Kubernetes-Cluster aufsetzen lässt – und zwar mit KubeOne.

Der Fokus liegt dabei nicht auf einem vollautomatisierten Platform-as-a-Service-Angebot, sondern auf einem flexiblen Setup für Nutzer:innen, die ihre Infrastruktur bewusst selbst gestalten möchten – sei es aus Kostengründen, wegen regulatorischer Anforderungen oder schlicht zur Wahrung der eigenen Kontrolle.

Warum KubeOne?

Wer Kubernetes auf Bare Metal oder bei einem IaaS-Provider wie Hetzner betreiben möchte, steht schnell vor der Frage: Wie automatisiere ich den Aufbau und die Wartung meines Clusters, ohne direkt in komplexere Werkzeuge wie Cluster API, Rancher oder OpenShift einsteigen zu müssen.

KubeOne trifft hier einen praktischen Sweet Spot:

• Deklarativ: Cluster-Topologie und Konfiguration werden in YAML-Dateien definiert.
• Flexibel: Unterstützt verschiedenste Infrastrukturen, darunter auch vSphere, AWS – und eben Bare Metal bzw. Hetzner.
• Kubeadm-basiert: Baut auf dem offiziellen Kubernetes-Installer auf.
• Open Source & aktiv gepflegt: Entwickelt von Kubermatic, mit Fokus auf Transparenz und Wartbarkeit.

Vorgehen

Bevor es mit der eigentlichen Cluster-Erstellung losgehen kann, braucht es eine solide Grundlage – sowohl auf Seiten der Infrastruktur als auch bei den eingesetzten Tools. Für unsere Umgebung setzen wir auf dedizierte Root-Server von Hetzner, die durch garantierte Ressourcen und eine stabile Netzwerkanbindung überzeugen. Alternativ ließe sich das Setup auch mit Hetzners Cloud-Instanzen realisieren. Für produktive Workloads bieten Bare-Metal-Server jedoch Vorteile.

Als Betriebssystem kommt eine gängige Linux-Distribution zum Einsatz – in unserem Fall Ubuntu –, da KubeOne auf kubeadm aufsetzt und somit auf die klassischen Kubernetes-Umgebungen ausgerichtet ist. Die Orchestrierung der Cluster-Komponenten übernimmt KubeOne, während Terraform für die Provisionierung der Infrastruktur zuständig ist. Besonders elegant lässt sich das mit dem offiziellen Hetzner Cloud Provider für Terraform lösen, wobei bei Root-Servern etwas mehr Handarbeit erforderlich ist.

Ein funktionierender SSH-Zugang zu den Maschinen sowie öffentlich erreichbare IP-Adressen (mindestens für die Control-Plane) sind ebenfalls Voraussetzung. Nur so kann KubeOne die Nodes initialisieren, konfigurieren und das Cluster vollständig aufsetzen. Eine gute Vorbereitung dieser Komponenten sorgt dafür, dass der eigentliche Clusteraufbau später reibungslos verläuft.

Schritt 1: Infrastruktur und lokale Vorbereitung

Bevor ihr euch an die eigentliche Infrastruktur wagt, müssen die Werkzeuge lokal installiert sein. Konkret braucht ihr:

• Terraform
• KubeOne (passend zur gewünschten Cluster-Version, z. B. v1.10.x)
• Einen funktionierenden SSH-Zugang zu Hetzner (für Root-Server über Robot, für Cloud-Instanzen über das Hetzner Cloud Console)
• Hetzner API-Token (HCLOUD_TOKEN), um Ressourcen automatisiert anlegen zu können

Unter Linux lässt sich KubeOne z. B. so installieren:

curl -sfL get.kubeone.io | sh

Nach dem Download liegt kubeone im aktuellen Verzeichnis. Am besten verschiebt ihr es in ein Verzeichnis, das im PATH liegt.

Die aktuelle Version von Terraform lässt sich direkt von der HashiCorp-Webseite herunterladen. Beispiel für Linux (64-bit):

# Aktuelle Version prüfen und anpassen:
TERRAFORM_VERSION="1.8.4"

# Download und Entpacken
curl -LO "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip"
unzip terraform_${TERRAFORM_VERSION}_linux_amd64.zip

# Binärdatei verschieben
sudo mv terraform /usr/local/bin/

# Version prüfen
terraform version

Für den Zugriff auf die Hetzner Cloud API wird ein gültiges API-Token benötigt. Das Hetzner API-Token lässt sich im Hetzner Cloud Console unter Access → API Tokens erzeugen. In Terraform wird es z. B. so referenziert.

provider "hcloud" {
  token = var.hcloud_token
}

Wir empfehlen, das Token über Umgebungsvariablen ('HCLOUD_TOKEN') oder via .tfvars einzubinden und nicht im Klartext zu hinterlegen.

Schritt 2: Infrastruktur mit Terraform provisionieren

Die Infrastruktur für das Cluster bauen wir mit Terraform auf – basierend auf dem offiziellen Beispiel für Hetzner von Kubermatic. Dieses Setup enthält u.a.:

• Control-Plane- und Worker-Nodes
• Floating IPs
• SSH-Schlüssel
• Firewall-Regeln
• Netzwerk-Setup

Repository klonen

Wir empfehlen, mit dem offiziellen Beispiel zu starten:

git clone https://github.com/kubermatic/kubeone.git
cd kubeone/examples/terraform/hetzner

Terraform konfigurieren

Vor der Ausführung müssen einige Werte in der Datei terraform.tfvars gesetzt werden. Eine beispielhafte Konfiguration könnte so aussehen:

hcloud_token       = "your-hcloud-api-token"
ssh_public_key     = "~/.ssh/id_rsa.pub"
ssh_private_key    = "~/.ssh/id_rsa"
control_plane_type = "cpx31"
worker_type        = "cpx31"
location           = "nbg1"

Terraform ausführen

Sobald die Variablen gesetzt sind, kannst du die Infrastruktur provisionieren:

terraform init
terraform apply

Terraform legt dabei alle Ressourcen an und erzeugt am Ende strukturierte Ausgaben mit den IP-Adressen, SSH-Informationen und mehr – die später von KubeOne verwendet werden.

Um diese an KubeOne zu übergeben, exportierst du die Ausgabe in eine Datei:

terraform output -json > terraform-output.json

Übersicht der angelegten Ressourcen

Das Setup aus dem Beispiel-Repository erzeugt:

• 1 x Control-Plane-Node (Floating IP wird zugewiesen)
• 2 x Worker-Nodes
• Ein dediziertes Netzwerk (Subnetz, private Kommunikation zwischen Nodes)
• SSH-Zugänge für alle Maschinen
• Eine Basis-Firewall mit offenen Ports für SSH, ICMP und Kubernetes-Komponenten

Schritt 3: KubeOne-Konfiguration vorbereiten

Die Datei kubeone.yaml ist das zentrale Steuerungselement für den Clusteraufbau. Sie beschreibt, wie KubeOne das Cluster installieren soll – unabhängig von den konkreten Hosts, die zuvor mit Terraform provisioniert wurden. Während IP-Adressen und SSH-Zugänge aus der Datei terraform-output.json kommen, enthält kubeone.yaml Informationen zur Kubernetes-Version, zur Cloud-Anbindung und zu allgemeinen Cluster-Einstellungen.

Eine reduzierte Beispielkonfiguration könnte so aussehen:

apiVersion: kubeone.io/v1beta2
kind: KubeOneCluster
name: hetzner-cluster

versions:
  kubernetes: "1.29.2"

cloudProvider:
  hetzner: {}

Der Block cloudProvider.hetzner aktiviert z. B. automatisch das Hetzner-CSI-Plugin für Volumes. Weitere Optionen – etwa zum Netzwerk-Plugin, zu Container-Runtime oder zu Cluster-Features wie Audit Logs – können ebenfalls über diese Datei gesteuert werden.

Die eigentliche Zuordnung von IP-Adressen und SSH-Zugängen erfolgt nicht über diese YAML, sondern über die Datei terraform-output.json, die wir im vorherigen Schritt erzeugt haben.

Beim Aufruf von KubeOne sieht das dann so aus:

kubeone install -m terraform-output.json -c kubeone.yaml

Schritt 4: Cluster installieren

Sind die Infrastruktur und die Konfiguration einmal vorbereitet, übernimmt KubeOne den Rest. Mit dem Befehl kubeone install – wie im vorherigen Schritt gezeigt – wird das gesamte Cluster automatisiert aufgebaut.

KubeOne verbindet sich dabei via SSH mit den Hosts, prüft deren Zustand, installiert die Container Runtime sowie alle Kubernetes-Komponenten per kubeadm, setzt das Netzwerk-Plugin auf und bringt das Cluster in einen lauffähigen Zustand.

Am Ende steht ein funktionierender Cluster bereit – inklusive kubeconfig-Datei für den Zugriff, die standardmäßig im lokalen Verzeichnis ~/.kubeone/ abgelegt wird.

Viel Spaß beim Ausprobieren

Wir hoffen, dieser erste Einblick in die Cluster-Erstellung mit KubeOne hat euch weitergeholfen – oder zumindest Lust gemacht, es selbst einmal auszuprobieren. Gerade in Kombination mit Hetzner ergibt sich eine spannende Mischung aus Performance, Kostenkontrolle und technischer Freiheit.

Habt ihr Fragen oder bereits eigene Erfahrungen mit KubeOne auf Hetzner gesammelt? Dann freuen wir uns über euer Feedback oder eure Kommentare. Und wie immer gilt: Wer nicht alles selbst bauen möchte, bekommt bei uns natürlich auch Unterstützung – von der ersten Beratung bis zum voll gemanagten Cluster.