KubeOne auf Hetzner

Richte einen produktionsreifen Kubernetes-Cluster mit KubeOne als Provisioner ein.

Voraussetzungen

• lok8s CLI installiert
• hcloud CLI installiert und authentifiziert
• Ein SSH-Schlüsselpaar, das zu deinem Hetzner-Projekt hinzugefügt wurde
• Hetzner-Cloud-API-Token als HCLOUD_TOKEN exportiert

Cluster-Konfiguration

Erstelle clusters/example.com/cluster.lok8s.yaml mit kind: KubeOne (der Ordner trägt den Namen deiner Domain) und führe dann lo use example.com aus. Die Maschinen werden im Hetzner-Provider-Deskriptor deklariert: ein server-Eintrag pro Node, die Rolle steht im Label lok8s.dev/role. Alle Schlüssel erklärt Erster Cluster.

# clusters/example.com/cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: KubeOne
metadata:
  name: production
spec:
  kubernetes:
    version: "v1.35.5"
  cluster:
    # PFLICHT: eine Domain, die dir gehört; für API-Endpunkt und Zertifikate
    domain: example.com
  provider:
    name: hetzner
    config:
      cluster_name: production
      sshUser: root
      sshPrivateKey: ~/.ssh/id_ed25519
      sshPublicKey: ~/.ssh/id_ed25519.pub
      ssh-key:
        - name: production
          public-key-from-file: ~/.ssh/id_ed25519.pub
      network:
        - name: production
          ip-range: 10.0.0.0/16
          "#subnets":
            - network-zone: eu-central
              type: cloud
              ip-range: 10.0.0.0/24
      server:
        - name: cp-1
          type: cx33
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=control-plane
        - name: cp-2
          type: cx33
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=control-plane
        - name: cp-3
          type: cx33
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=control-plane
        - name: worker-1
          type: cpx31
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=worker
        - name: worker-2
          type: cpx31
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=worker

Bereitstellen

lo provision

Dies wird:

1. Hetzner-Cloud-Server für Control Plane und Worker erstellen
2. Das private Netzwerk einrichten
3. Kubernetes via KubeOne installieren
4. Die kubeconfig als .kubeconfig/production.yaml im Projekt ablegen, benannt nach metadata.name, Modus 0600. Deine ~/.kube/config wird nicht angefasst.

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.

Überprüfen

kubectl zeigt weiterhin auf den zuvor genutzten Kontext; wähle den neuen Cluster also explizit aus, sonst antwortet get nodes für deinen vorherigen Cluster:

export KUBECONFIG=.kubeconfig/production.yaml
kubectl get nodes
# (AGE trimmed — VERSION is what to check)
# NAME       STATUS   ROLES           VERSION
# cp-1       Ready    control-plane   v1.35.5
# cp-2       Ready    control-plane   v1.35.5
# cp-3       Ready    control-plane   v1.35.5
# worker-1   Ready    <none>          v1.35.5
# worker-2   Ready    <none>          v1.35.5

HA-Überlegungen

• Deklariere für die Produktion drei control-plane-Server
• Control-Plane-Nodes werden automatisch über Fehlerdomänen verteilt
• Das private Netzwerk (network[].ip-range) isoliert den Cluster-Traffic

Bootstrap-Addons hinzufügen

Cluster-Infra-Addons (CNI, CCM, cert-manager, Monitoring, …) stehen unter spec.bootstrap und werden beim Provisionieren in Reihenfolge angewendet:

  bootstrap:
    - cilium
    - ccm
    - monitoring

Führe lo bootstrap aus, um Bootstrap-Änderungen auf einen bestehenden Cluster anzuwenden; es wendet spec.bootstrap erneut an und überspringt den Infrastruktur-Abgleich. lo provision macht beides und lässt sich ebenfalls gefahrlos erneut ausführen.

Nächste Schritte

• Registrierung: beim kubehz-Dashboard registrieren
• GitHub Actions: Bereitstellung in CI automatisieren
• CAPI: alternativer Provisioner mit Cluster API

---

Doku-Status

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