Das Hetzner-Token

Ein Hetzner-Cloud-API-Token ist optional. Du brauchst nie eines, um dich anzumelden, das Dashboard zu durchsuchen, Listenpreise zu sehen oder einen gehosteten Cluster nur mit Control Plane zu betreiben. Ein Token schaltet zwei Dinge ein: die exakten Preise deines Kontos und die Bereitstellung (Worker-Pools und SSH-Keys auf deinem eigenen Hetzner-Konto).

Ohne Token

Du siehst trotzdem alles, zu Listenpreisen. Das Dashboard zeigt Hetzner-Standorte, Maschinentypen und Preise. kubehz liest sie mit seinem eigenen Plattform-Token. Dein Hetzner-Konto kann andere Preise haben (zum Beispiel ausgehandelte Preise). Deshalb zeigt das Dashboard Hetzners Listenpreise und markiert sie mit einem Sternchen (*): Sie sind eine Schätzung, nicht deine Rechnung.

Du kannst einen gehosteten Cluster erstellen. Ein gehosteter Cluster nur mit Control Plane braucht kein Token, denn kubehz betreibt die Control Plane auf eigener Infrastruktur. Ein Token gibt diesem Cluster Worker auf deinem Konto, und diese Entscheidung triffst du einmal, bei der Erstellung.

Ein Cluster, den du ohne verbundenes Token erstellst, kann später keine Worker-Pools mehr bekommen. Für Worker verbindest du ein Token und erstellst den Cluster neu (siehe Worker-Pools). Wenn du jemals Worker auf dem Cluster haben möchtest, verbinde ein Token, bevor du ihn erstellst.

Mit Token

Verbinde ein Token im Erstell-Assistenten. Du kannst ein Token auch später zum Konto hinzufügen, denn es ist ein Tenant-Credential, kein Cluster-Credential. Aber Worker-Pools wählst du bei der Erstellung des Clusters: Ein Cluster ohne verbundenes Token kann später keine Worker-Pools mehr bekommen, außer du erstellst ihn neu (siehe Worker-Pools). Ein Token, das du später verbindest, liefert trotzdem kontogenaue Preise. Die Art des Tokens entscheidet, was es einschaltet:

Ein Read-&-Write-Token schaltet die Bereitstellung ein. Das Dashboard wechselt von Listenpreisen zu den exakten Preisen deines Kontos. Du kannst Worker-Pools erstellen und skalieren: kubehz erstellt die Server auf deinem Konto, und du zahlst direkt an Hetzner, ohne kubehz-Aufschlag. Du kannst auch die SSH-Keys für die Worker-Nodes verwalten.

Ein Read-only-Token liefert trotzdem kontogenaue Preise. Das Token authentifiziert sich, also werden die Preise zu den echten Zahlen deines Kontos. Aber die Bereitstellung bleibt gesperrt, und das Dashboard sagt dir das. Um bereitzustellen, ersetze das Token durch ein Read-&-Write-Token.

Das Token erstellen

Wähle in der Hetzner Cloud Console das Projekt für deine Worker. Wähle dann Security → API tokens → Generate API token. Nimm Read & Write, wenn du bereitstellen willst. Read genügt für die Preise allein.

Wie kubehz das Token prüft

Wenn du ein Token verbindest oder ersetzt, prüft kubehz das Token, bevor es das Token speichert:

• Das Token muss sich authentifizieren. kubehz weist ein Token zurück, das Hetzner ablehnt.
• Das Token muss zum richtigen Projekt gehören. Bei einem Cluster, der schon Server hat, bestätigt kubehz, dass das Token zum selben Hetzner-Projekt wie diese Worker gehört. kubehz weist ein Token aus einem anderen Projekt zurück, damit das Token deine bestehenden Nodes nicht strandet. (Ein hcloud-Token gehört zu genau einem Projekt.) Manchmal kann die Prüfung nicht laufen: Es gibt noch keine bereitgestellten Server, oder Hetzner ist nicht erreichbar. Dann gibt die Prüfung nach, und kubehz speichert das Token.

Wie kubehz das Token speichert

Verschlüsselt gespeichert, nie wieder angezeigt. kubehz verschlüsselt das Token, bevor das Token unsere Datenbank erreicht. kubehz nutzt das Token nur, um die Ressourcen deines eigenen Clusters zu verwalten. Das Dashboard zeigt den Wert nie wieder. Es zeigt nur, ob ein Token verbunden ist und seit wann.

Du kannst das Token jederzeit ersetzen. Um ein Token zu verbinden oder zu ersetzen, brauchst du eine frische 2FA-Bestätigung. Du kannst das Token in der Hetzner Cloud Console widerrufen, wann immer du willst.

Mit der lo-CLI

Wenn du mit lok8s bereitstellst, beansprucht lo provision mit einem KUBEHZ_TOKEN den Cluster direkt für deinen Tenant. Ein KUBEHZ_TOKEN ist ein clusters:write-API-Token, das du im Dashboard unter Zugriff → API-Tokens erstellst. Um kubehz auch dein HCLOUD_TOKEN für die Dashboard-Bereitstellung zu geben, opte ein:

# cluster.lok8s.yaml
spec:
  kubehz:
    hosting: hosted
    connectHcloudToken: true   # HCLOUD_TOKEN zur Bereitstellung an kubehz senden

Das ist Opt-in. Ohne connectHcloudToken: true nutzt lo dein HCLOUD_TOKEN nur lokal und sendet es nie an kubehz. Ohne ein KUBEHZ_TOKEN sendet lo überhaupt nichts an kubehz.

Nächste Schritte

• Gehostete Control Plane: die Form, der Preis und der Hosted-Weg insgesamt.
• Worker-Pools: Pools, Skalierung und Autoscaling (braucht ein Read-&-Write-Token).
• Wie es funktioniert: die Vertrauensgrenze, die das Token delegiert.

---

Doku-Status

Aspekt	Detail
Zustand	live: optionales Token, Read & Write schaltet die Bereitstellung ein
Zuletzt geprüft	2026-10-30