Das Hetzner-Token

Ein Hetzner-Cloud-API-Token zu verbinden ist optional. Du brauchst keines, um dich anzumelden, das Dashboard zu durchstöbern, Listenpreise zu sehen oder einen gehosteten Cluster nur mit Control Plane zu betreiben. Ein Token schaltet zwei Dinge frei: 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, bedient aus kubehz’ eigenem Plattform-Token. Da dein Hetzner-Konto abweichende (zum Beispiel ausgehandelte) Preise haben kann, sind das Hetzners Listenpreise, mit einem Sternchen (*) markiert, damit klar ist: eine Schätzung, nicht deine Rechnung.

Du kannst einen gehosteten Cluster erstellen. Ein Cluster nur mit Control Plane braucht kein Token: kubehz betreibt die Control Plane auf eigener Infrastruktur. Ein Token ist das, was diesem Cluster Worker auf deinem Konto ermöglicht, und diese Entscheidung fällt einmalig bei der Erstellung: Ein Cluster, der ohne verbundenes Token erstellt wurde, kann später keine Worker-Pools mehr bekommen; du müsstest ein Token verbinden und den Cluster neu erstellen (siehe Worker-Pools). Verbinde es vor dem Erstellen, wenn du jemals Worker darauf haben möchtest.

Mit Token

Verbinde ein Token im Erstell-Assistenten. Du kannst es später zum Konto hinzufügen (es ist ein Tenant-Credential, kein Cluster-Credential), aber Worker-Pools sind zur Cluster-Erstellung fixiert: ein ohne Token erstellter Cluster bekommt später keine Pools, ohne neu erstellt zu werden (siehe Worker-Pools). Später verbinden liefert weiterhin kontogenaue Preise. Welches Token du nimmst, entscheidet, was freigeschaltet wird:

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

Ein Read-only-Token liefert weiterhin die exakten Preise deines Kontos. Es authentifiziert sich, also werden die Preise zu den echten Zahlen deines Kontos, aber die Bereitstellung bleibt gesperrt, und das Dashboard sagt das. Um bereitzustellen, ersetze es durch ein Read-&-Write-Token.

Das Token erstellen

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

Wie es beim Verbinden geprüft wird

Beim Verbinden oder Austauschen eines Tokens prüft kubehz es, bevor es gespeichert wird:

• Es muss sich authentifizieren: Ein Token, das Hetzner ablehnt, wird direkt zurückgewiesen.
• Es muss das richtige Projekt sein: Bei einem Cluster, der bereits Server hat, bestätigt kubehz, dass das Token zum selben Hetzner-Projekt wie diese Worker gehört. Ein Token aus einem anderen Projekt wird abgelehnt, damit es deine bestehenden Nodes nicht strandet. (Ein hcloud-Token gehört zu genau einem Projekt. Wo die Prüfung nicht laufen kann, weil es noch keine bereitgestellten Server gibt oder Hetzner nicht erreichbar ist, greift sie nachsichtig und speichert das Token.)

Wie es gespeichert wird

Verschlüsselt gespeichert, nie zurückgegeben. Das Token wird verschlüsselt, bevor es unsere Datenbank berührt, und ausschließlich zur Verwaltung der Ressourcen deines eigenen Clusters verwendet. Das Dashboard zeigt den Wert nie wieder, sondern nur, ob ein Token verbunden ist und seit wann. Du kannst es jederzeit ersetzen; das Verbinden oder Austauschen eines Tokens erfordert frisches 2FA. Widerrufe es in der Hetzner Cloud Console, wann immer du willst.

Mit der lo-CLI

Wenn du die Bereitstellung aus lok8s steuerst, beansprucht lo provision mit einem KUBEHZ_TOKEN (ein clusters:write-API-Token, erstellt im Dashboard unter Access → API Tokens) den Cluster direkt für deinen Tenant. Um kubehz auch dein HCLOUD_TOKEN für die Dashboard-Bereitstellung zu übergeben, 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 wird dein HCLOUD_TOKENnur lokal von lo verwendet und nie an kubehz gesendet. Ohne KUBEHZ_TOKEN wird überhaupt nichts an kubehz gesendet.

Nächste Schritte

• Gehostete Control Plane: Tarife 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 frei
Zuletzt geprüft	2026-07-16