Cluster beanspruchen

Das Beanspruchen weist nach, dass ein registrierter Cluster dir gehört, und ordnet ihn deinem kubehz-Konto zu.

Die Registrierung meldet einen Cluster lediglich an — er wird als pending (ausstehend) angelegt und gehört niemandem. Jeder könnte eine beliebige Domain anmelden, deshalb braucht Eigentum einen Nachweis. Dafür gibt es zwei Wege: den bei der Registrierung ausgegebenen Claim-Code (am einfachsten), oder die Verifizierung, dass der SSH-Schlüssel, mit dem der Cluster bereitgestellt wurde, in deinem Hetzner-Cloud-Konto vorhanden ist.

Option 1 — Claim-Code (am einfachsten)

Die Registrierung gibt einen einmaligen Claim-Code aus. Hast du einen? Dann ist das Beanspruchen ein einziges Einfügen:

Öffne das Dashboard unter app.kubehz.cloud und melde dich an
Gehe zur Seite Beanspruchen (Claim)
Füge den Claim-Code ein — fertig. Der Cluster wird deinem Tenant zugeordnet und seine Detailseite öffnet sich.

Ein paar Eigenschaften, die man kennen sollte:

Provider-agnostisch — der Code funktioniert ohne jedes Hetzner-Token, für jeden Cluster.
Wird beim Einlösen verbraucht — ein Code beansprucht genau einen Cluster, einmal.
Kein Orakel — ein falscher, abgelaufener oder bereits verwendeter Code liefert stets dieselbe Antwort "not found"; die Claim-Seite verrät nicht, was davon zutraf. Funktioniert dein Code nicht mehr, weiche auf die Fingerprint-Verifizierung unten aus oder registriere neu, um einen frischen Code zu erhalten.

Option 2 — SSH-Fingerprint + Hetzner-Token

Kein Claim-Code zur Hand? Weise das Eigentum über den SSH-Schlüssel nach, mit dem der Cluster bereitgestellt wurde: Er muss in deinem Hetzner-Cloud-Konto vorhanden sein.

Was du benötigst

Den MD5-Fingerprint, den lo provision / lo kubehz register ausgegeben hat. Du kannst ihn jederzeit aus dem in deiner cluster.lok8s.yaml konfigurierten öffentlichen Schlüssel (spec.hcloud.sshPublicKeyFile) neu berechnen:
bash
```
ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub
```
Einen Hetzner-Cloud-API-Token für das Projekt, das diesen SSH-Schlüssel enthält. Ein Read-only-Token genügt. Erstelle ihn in der Hetzner Cloud Console unter Security → API tokens.

Cluster beanspruchen

Öffne das Dashboard unter app.kubehz.cloud und melde dich an
Gehe zur Seite Beanspruchen (Claim)
Füge den Fingerprint ein — MD5:aa:bb:cc:… oder die bloße Form aa:bb:cc:…, beide werden akzeptiert
Füge deinen Hetzner-Cloud-API-Token ein
Klicke auf Cluster beanspruchen

kubehz verwendet den Token einmalig, serverseitig, um die SSH-Schlüssel in deinem Hetzner-Projekt aufzulisten und zu prüfen, ob einer davon zum Fingerprint passt. Bei Erfolg wird der Cluster deinem Tenant zugeordnet und seine Detailseite öffnet sich.

Wie dein Hetzner-Token behandelt wird

Einmalige Verwendung — ein einziger Abruf deiner SSH-Schlüssel zum Zeitpunkt des Beanspruchens, sonst nichts
Niemals gespeichert — direkt nach der Verifizierung verworfen; er wird weder in die Datenbank geschrieben noch geloggt
Minimale Rechte — ein Read-only-Token genügt; kubehz erstellt, ändert oder löscht niemals etwas in deinem Hetzner-Konto
Best Practice: Erstelle einen dedizierten Token nur für das Beanspruchen und lösche ihn danach in der Hetzner Console

Sicherheitshinweise

Der Fingerprint ist eine öffentliche Information: Er identifiziert deinen öffentlichen Schlüssel, kann sich aber nicht als du ausgeben. Genau deshalb verlangt der Fingerprint-Weg zusätzlich die Prüfung per Hetzner-Token.
Die Plattform verbindet sich niemals in deinen Cluster hinein. Statusdaten fließen ausschließlich ausgehend, über den Heartbeat-CronJob.
Schlägt die Verifizierung fehl, meldet das Dashboard dies ("Claim verification failed") und nichts wird zugeordnet.

Nach dem Beanspruchen

Der Cluster verlässt den Status pending und erscheint sofort in deiner Cluster-Liste
Statusdetails (Nodes, Komponentenstatus, Zertifikatsablauf) füllen sich mit den eintreffenden Heartbeats, aktualisiert alle 5 Minuten
Connected bedeutet: In den letzten 15 Minuten ging ein Heartbeat ein; zusätzlich leitet das Dashboard aus der Heartbeat-Historie eine 30-Tage-Uptime ab

Fehlerbehebung

Symptom	Lösung
Claim-Code "not found"	Codes sind einmalig und verfallen mit der ausstehenden Registrierung — registriere neu, um einen frischen Code zu erhalten, oder nutze den Weg Fingerprint + Token
Fingerprint wird nicht akzeptiert	Mit `ssh-keygen -E md5` neu berechnen — kubehz vergleicht die MD5-Form, weil Hetzner MD5-Fingerprints bereitstellt
Verifizierung schlägt trotz korrektem Fingerprint fehl	Stelle sicher, dass der Token zu dem Hetzner-Projekt gehört, das den SSH-Schlüssel tatsächlich enthält
Schlüssel fehlt bei Hetzner	Der öffentliche Schlüssel aus `cluster.lok8s.yaml` muss in deinem Hetzner-Cloud-Projekt existieren (das tut er, wenn lok8s den Cluster damit bereitgestellt hat)
Cluster noch nicht registriert	Führe zuerst `lo kubehz register` aus — siehe Registrierung

Nächste Schritte

Dashboard — was du nach dem Beanspruchen sehen und tun kannst
Registrierung — die CLI-Hälfte des Handshakes
Preise — was der kostenlose Tarif abdeckt

Doku-Status

Aspekt	Detail
Zustand	aktiv
Zuletzt geprüft	2026-07-10