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 mit dem Status Creating angelegt und gehört niemandem. Jeder könnte eine beliebige Domain anmelden, deshalb braucht Eigentum einen Nachweis. Die Seite Beanspruchen (Claim) im Dashboard bietet drei Nachweise, und ein vierter Weg überspringt das Beanspruchen ganz:

Nachweis	Was es braucht	Wann du es nutzt
Claim-Schlüssel (Tab Fingerprint)	Den Fingerprint, den lo kubehz register ausgegeben hat.	Der Normalfall: Du hast mit HCLOUD_TOKEN in deiner Shell provisioniert.
Claim-Code	Den installierten Heartbeat-Agent.	Jeder Cluster, jeder Provider; kein Hetzner-Projekt beteiligt.
Per Agent (Nonce)	Den installierten Heartbeat-Agent plus einen lo-Befehl.	Du bist ohnehin an der CLI und willst, dass das Dashboard die Bestätigung des Agents abwartet.
Direkte Zuordnung	KUBEHZ_TOKEN in deiner Shell bei der Registrierung.	CI und Automatisierung. Der Cluster registriert sich direkt auf deinem Tenant; es gibt nichts zu beanspruchen.

Option 1: der Claim-Schlüssel (üblich)

Ist HCLOUD_TOKEN gesetzt, fordert lo kubehz register bei der API einen Claim-Schlüssel an und lädt dessen öffentliche Hälfte unter dem Namen kubehz-claim-<domain> in dein Hetzner-Cloud-Projekt hoch. Nur der Projektbesitzer kann diesen Schlüssel halten, also ist sein Fingerprint der Nachweis. Kein Token wird irgendwo eingefügt.

1. Öffne das Dashboard unter app.kubehz.cloud und melde dich an
2. Gehe zur Seite Beanspruchen (Claim) und wähle den Tab SSH-Fingerprint
3. Füge den Fingerprint aus der CLI-Ausgabe ein: MD5:aa:bb:cc:… oder die bloße Form aa:bb:cc:… (beide werden akzeptiert)
4. Klicke auf Cluster beanspruchen

kubehz vergleicht den Fingerprint mit dem Claim-Schlüssel, den es für diesen Cluster ausgestellt hat. Bei Erfolg wird der Cluster deinem Tenant zugeordnet und seine Detailseite öffnet sich. Dieselbe Prüfung geht auch aus einem Skript:

curl -X POST https://api.kubehz.cloud/api/claims/verify \
  -H "Authorization: Bearer $KUBEHZ_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"fingerprint":"aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99"}'

Hast du die CLI-Ausgabe verloren, steht der Fingerprint in der Hetzner Console unter Security → SSH keys. Ein erneuter Lauf von lo kubehz register rotiert den Schlüssel und gibt den neuen Fingerprint aus.

Legacy: der Provisionierungs-Schlüssel

Ein Cluster, der ohne HCLOUD_TOKEN registriert wurde, wird mit dem MD5-Fingerprint des SSH-Schlüssels aus deinem Provider-Deskriptor (sshPublicKey) angemeldet. Existiert dieser Schlüssel in deinem Hetzner-Cloud-Projekt, akzeptiert derselbe Fingerprint-Tab auch ihn. Du kannst ihn jederzeit neu berechnen:

# der von sshPublicKey in deinem Provider-Deskriptor benannte Schlüssel
ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub

Option 2: der Claim-Code

Setzt den installierten Heartbeat-Agent voraus: Er erzeugt den Code beim ersten Lauf. Gibt lo kubehz claim-code nichts aus, ist der Agent noch nicht gelaufen.

Der Agent erzeugt bei seinem ersten Lauf einen einmaligen Claim-Code in deinem Cluster. Gib ihn mit lo kubehz claim-code aus (auf diesen Cluster gerichtet). Dann ist das Beanspruchen ein einziges Einfügen:

1. Öffne das Dashboard unter app.kubehz.cloud und melde dich an
2. Gehe zur Seite Beanspruchen (Claim) und wähle den Tab Claim-Code
3. 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-Projekt, 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 den Claim-Schlüssel oben aus.
• Einmalig erzeugt: Der Agent legt den Code bei seinem ersten Lauf an und rotiert ihn nie; lo kubehz claim-code gibt bis zur Einlösung immer denselben Code aus.

Option 3: per Agent (Nonce)

Braucht ebenfalls den Heartbeat-Agent. Hier erzeugt das Dashboard das Geheimnis, und dein Cluster meldet es zurück:

1. Wähle auf der Seite Beanspruchen den Tab Per Agent. Das Dashboard erzeugt eine Challenge-Nonce (khzn_…) und wartet.

2. Lege sie mit der CLI in deinem Cluster ab:

   lo kubehz claim --nonce khzn_...

3. Der Agent meldet die Nonce mit seinem nächsten Heartbeat zurück. Das Dashboard sieht sie und ordnet den Cluster deinem Tenant zu.

Die Nonce ist einmalig und kurzlebig; läuft die Seite in ein Timeout, erzeuge eine neue.

Option 4: gar kein Beanspruchen

Mit KUBEHZ_TOKEN in deiner Shell (ein clusters:write-API-Token aus dem Dashboard, Zugriff → API-Tokens) registriert lo kubehz register den Cluster direkt auf deinem Tenant. Er erscheint sofort in deiner Cluster-Liste; es gibt keinen Claim-Schritt. Das ist der Weg für CI. Bewahre den Token in einem Secret-Store auf, nie in der Spec.

Sicherheitshinweise

• Ein Fingerprint ist eine öffentliche Information: Er identifiziert einen öffentlichen Schlüssel, kann sich aber nicht als du ausgeben. Der Claim-Schlüssel funktioniert, weil nur dein Hetzner-Projekt den Schlüssel halten kann, den kubehz für deinen Cluster ausgestellt hat.
• Die Plattform verbindet sich niemals in deinen Cluster hinein. Statusdaten fließen ausschließlich ausgehend, über den Heartbeat-Agent.
• 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 Creating 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
Fingerprint wird nicht akzeptiert	Nimm den Fingerprint, den lo kubehz register ausgegeben hat, oder lies ihn in der Hetzner Console ab (Security → SSH keys, Schlüssel kubehz-claim-<domain>). Führe lo kubehz register mit gesetztem HCLOUD_TOKEN erneut aus, um einen frischen Schlüssel auszustellen
Claim-Code “not found”	Codes sind einmalig und verfallen mit der Registrierung. Nutze den Claim-Schlüssel
Die Seite “Per Agent” wartet endlos	Der Agent hat seit dem Ablegen der Nonce nicht gesendet. Prüfe kubectl -n kubehz-system get cronjob kubehz-heartbeat und erzeuge dann eine neue Nonce
Schlüssel fehlt bei Hetzner	lo kubehz register konnte den Claim-Schlüssel nicht hochladen. Prüfe, ob HCLOUD_TOKEN Read-&-Write-Rechte auf das Projekt hat, und führe den Befehl erneut aus
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-09-05