Schnellstart

Bringe in etwa 15 Minuten einen Kubernetes-Cluster auf Hetzner zum Laufen.

Voraussetzungen

• Ein Hetzner Cloud-Konto und ein Projekt-API-Token mit Lese- und Schreibrechten (Hetzner Console → Security → API tokens):

  export HCLOUD_TOKEN="<dein-token>"

• Die lok8s CLI lo, ein einzelnes statisches Go-Binary. Lade es aus einem lok8s-Release, prüfe es gegen checksums.txt und installiere es dann. Wähle das Archiv für dein System (linux oder darwin, amd64 oder arm64):

  V=v0.12.0; A=lo-linux-amd64.tar.gz
  curl -fsSLO "https://github.com/kernpilot/lok8s/releases/download/${V}/${A}"
  curl -fsSLO "https://github.com/kernpilot/lok8s/releases/download/${V}/checksums.txt"
  sha256sum --ignore-missing -c checksums.txt   # macOS: shasum -a 256 --ignore-missing -c checksums.txt
  tar -xzf "${A}" lo && mkdir -p "$HOME/.local/bin" && install -m 0755 lo "$HOME/.local/bin/lo"

  Lege dann dein Projekt an und installiere die gepinnte KubeOne-Toolchain in seinen Ordner .bin/. Nichts berührt dein System:

  mkdir my-project && cd my-project
  lo init project
  lo toolchain install --groups core,local,cloud

  Nutzt du bereits b? Diese beiden installieren lo und dieselbe Toolchain:

  b env add github.com/kernpilot/lok8s#kubeone
  b install

• Ein SSH-Schlüsselpaar (Ed25519 empfohlen)

• Eine Domain, die dir gehört: der API-Endpunkt und die Zertifikatsnamen des Clusters leiten sich daraus ab. Du setzt sie in Schritt 1; die Referenzkonfiguration liefert example.com als Platzhalter, nicht als Standard.

1. Cluster-Konfiguration erstellen

lo hält pro Cluster einen Ordner, benannt nach der Domain des Clusters: clusters/<domain>/cluster.lok8s.yaml. Lege den Ordner in deinem Projekt an und speichere die Datei dort:

mkdir -p clusters/example.com
# füge die Datei unten in clusters/example.com/cluster.lok8s.yaml ein
lo use example.com

lo use markiert die Domain als aktiv. Jeder spätere Befehl weiß damit, welchen Cluster du meinst.

# clusters/example.com/cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: KubeOne
metadata:
  name: my-cluster
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
    # Die Maschinen, in Hetzners eigenen Begriffen: Jeder `server`-Eintrag wird
    # zu einem `hcloud server create`, seine Schlüssel sind hcloud-Flags. Die
    # Rolle kommt aus dem Label lok8s.dev/role.
    config:
      cluster_name: my-cluster
      sshUser: root
      sshPrivateKey: ~/.ssh/id_ed25519
      sshPublicKey: ~/.ssh/id_ed25519.pub
      ssh-key:
        - name: my-cluster
          public-key-from-file: ~/.ssh/id_ed25519.pub
      network:
        - name: my-cluster
          ip-range: 10.0.0.0/16
          "#subnets":
            - network-zone: eu-central
              type: cloud
              ip-range: 10.0.0.0/24
      server:
        # 1 Control Plane für Dev; für HA zwei weitere ergänzen
        - name: cp-1
          type: cpx32
          image: ubuntu-24.04
          # fsn1, nbg1 oder hel1
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=control-plane
        - name: worker-1
          type: cpx32
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=worker
        - name: worker-2
          type: cpx32
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=worker

Das Beispiel nutzt für jeden Server cpx32 (4 vCPUs, 8 GB RAM). Jeder Typ mit mindestens gleich vielen vCPUs und gleich viel RAM, den dein Hetzner-Konto am Standort anbietet, funktioniert auch.

Was lieferbar ist, unterscheidet sich je Konto und ändert sich stündlich: Lehnt Hetzner einen Typ ab, nimm einen anderen Typ oder einen anderen Standort (fsn1, nbg1 oder hel1).

Ändere domain (und den Ordnernamen) vor dem nächsten Schritt auf eine Domain, die dir gehört: Nichts in dieser Datei kann sie für dich erraten. Die drei SSH-Pfade setzen einen Ed25519-Schlüssel mit Standardnamen voraus (~/.ssh/id_ed25519); heißt deiner anders oder liegt er woanders, passe auch die an.

2. Bereitstellen

lo provision

Dies erstellt deine Control Plane und Worker-Nodes auf Hetzner Cloud. Die kubeconfig wird als .kubeconfig/my-cluster.yaml im Projekt abgelegt, benannt nach metadata.name. Deine ~/.kube/config wird nicht angefasst.

Die Bereitstellung dauert typischerweise 10–15 Minuten. Hetzner rechnet die drei Server stündlich zu seinen veröffentlichten Preisen ab. Mit lo destroy kannst du jederzeit alles wieder löschen.

3. Ü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:

export KUBECONFIG=.kubeconfig/my-cluster.yaml
kubectl get nodes

Deine Control Plane und Worker-Nodes sollten im Zustand Ready erscheinen.

4. Bei kubehz registrieren (optional)

Nur dieser Schritt braucht ein kostenloses kubehz-Konto; die Voraussetzungen oben sind alles, was der Cluster selbst benötigt. Die Registrierung ist für die ersten 25 Konten offen, danach nur mit Einladung (siehe Dashboard & Konto).

Verbinde deinen Cluster mit dem kubehz-Dashboard für schreibgeschützte Zustandssichtbarkeit. Die Registrierung ist nur ausgehend: kubehz erhält niemals Zugriff in deinen Cluster.

lo kubehz register

Dies meldet den Cluster mit dem Status Creating an. Beanspruche ihn anschließend unter app.kubehz.cloud, um den Besitz nachzuweisen und ihn mit deinem Konto zu verknüpfen (registrieren → beanspruchen → besitzen). Siehe Registrierung für die Details und was das Dashboard anzeigt.

Nächste Schritte

• Erster-Cluster-Walkthrough: detaillierte Konfigurationsreferenz
• Dashboard & Konto: das Dashboard, Zugriff und Konto erkunden
• Wie es funktioniert: das Modell, die Vertrauensgrenze und deine Daten
• Self-Hosted-Leitfaden: fortgeschrittene Self-Hosted-Einrichtung
• Gehostete Control Plane: der delegierte Weg

Doku-Status

Aspekt	Detail
Zustand	Live: entspricht dem ausgelieferten CLI-Ablauf; die Bereitstellungsdauer ist eine konservative Schranke, auf dieser Topologie noch nicht gemessen
Zuletzt geprüft	2026-09-05