Registrierung

Registriere deinen Self-Hosted-Cluster bei der kubehz-Plattform für die Sichtbarkeit im Dashboard.

Registrierung und Beanspruchen sind die zwei Hälften eines Handshakes:

1. Registrieren (CLI) — meldet den Cluster und den Fingerprint seines SSH-Schlüssels bei kubehz an. Der Cluster wird als pending (ausstehend) angelegt und ist noch keinem Konto zugeordnet.
2. Beanspruchen (Dashboard) — du weist nach, dass der SSH-Schlüssel zu deinem Hetzner-Cloud-Konto gehört. Der Cluster wird deinem Tenant zugeordnet. Siehe Cluster beanspruchen.

Voraussetzungen

• Ein laufender Kubernetes-Cluster, bereitgestellt mit lok8s
• kubectl konfiguriert und mit deinem Cluster verbunden
• Ein kubehz-Konto — nötig für das Beanspruchen, nicht für die Registrierung

Konfiguration

Füge den kubehz-Block zu deiner cluster.lok8s.yaml hinzu:

spec:
  kubehz:
    hosting: self
    access: registered       # oder 'managed' fuer die Verwaltungsfunktionen (Supporter+)
    apiUrl: https://api.kubehz.cloud

apiUrl muss HTTPS sein — die CLI lehnt Endpunkte mit unverschlüsseltem HTTP ab.

Zugriffsebenen

Ebene	Was kubehz sieht	Kosten
none	Nichts — keine Verbindung	Kostenlos
registered	Nodes, K8s-Version, Komponentenstatus, Zertifikatsablauf, Uptime	Kostenlos (bis zu 2 Cluster)
managed	Alles aus registered, plus die Verwaltungsdaten hinter Healing-Richtlinien, Kapazitäts-Überwachung und der Verwaltung des gewünschten Zustands (Upgrades/Skalierung)	Supporter-Abo oder höher

Registrieren

Die Registrierung läuft automatisch während lo provision (sofern access nicht none ist). Du kannst sie auch jederzeit manuell ausführen:

lo kubehz register

Dies sendet eine einzelne Anfrage an POST /api/clusters/register auf der konfigurierten apiUrl, mit genau zwei Feldern: der Cluster-Domain und dem MD5-Fingerprint des öffentlichen SSH-Schlüssels des Clusters. Zu diesem Zeitpunkt ist weder ein Token noch ein Konto nötig, und es wird nichts in deinem Cluster installiert — die Anfrage stellt die CLI auf deinem Rechner, nicht der Cluster selbst.

Bei Erfolg gibt die CLI aus, was du für das Beanspruchen benötigst — einen einmaligen Claim-Code (der einfachste Weg: auf der Claim-Seite des Dashboards einfügen — fertig) und den SSH-Schlüssel-Fingerprint für den alternativen Verifizierungsweg:

kubehz: cluster 'example.com' registered (pending). Claim it in the dashboard:
  fingerprint: MD5:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99

Der Claim-Code funktioniert ohne jedes Hetzner-Token und wird beim Einlösen verbraucht — siehe Cluster beanspruchen für beide Wege.

Der Cluster ist jetzt pending: keinem Konto zugeordnet und für niemanden sichtbar, bis du ihn beanspruchst. Nicht beanspruchte (ausstehende) Registrierungen werden nach 30 Tagen automatisch gelöscht — du kannst jederzeit einfach neu registrieren.

Warum ein MD5-Fingerprint?

Der Eigentumsnachweis erfolgt gegen die SSH-Schlüssel in deinem Hetzner-Cloud-Konto, und Hetzner stellt MD5-Fingerprints bereit — deshalb verwendet kubehz die MD5-Form. Du kannst ihn jederzeit selbst berechnen:

ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub

Der Fingerprint identifiziert deinen öffentlichen Schlüssel. Er ist kein Geheimnis und verrät nichts über deinen privaten Schlüssel.

Cluster beanspruchen

Die Registrierung allein ordnet den Cluster niemandem zu. Beanspruche ihn im Dashboard — füge den Claim-Code ein, oder verifiziere per SSH-Fingerprint + Hetzner-Token. Die Schritt-für-Schritt-Anleitung findest du unter Cluster beanspruchen.

Heartbeats

Der Cluster-Status im Dashboard stammt von einem leichtgewichtigen CronJob namens kubehz-heartbeat im Namespace kubehz-system. Alle 5 Minuten sendet er per POST an die kubehz-API:

• Kubernetes-Version
• Node-Namen, -Status und -Rollen
• Status der Control-Plane-Komponenten
• Zertifikatsablauf

Der Agent läuft mit rein lesendem RBAC und gehärtetem Security-Kontext und stellt ausschließlich ausgehende Anfragen — die kubehz-Plattform verbindet sich niemals in deinen Cluster hinein.

Der Agent wird nicht automatisch installiert: seine Manifeste werden mit lok8s ausgeliefert und du wendest sie selbst an — die Installationsbefehle findest du im lok8s kubehz-Platform-Guide. Bis zur Installation zeigt das Dashboard deinen Cluster als Disconnected an (Registrierung und Beanspruchen funktionieren auch ohne den Agent).

Fehlerbehebung

# Registrierungsstatus aus Sicht der CLI
lo kubehz status

# Ist der Heartbeat-CronJob vorhanden?
kubectl -n kubehz-system get cronjob kubehz-heartbeat

# Logs der letzten Heartbeat-Laeufe
kubectl -n kubehz-system logs -l app=kubehz-heartbeat

# Registrierung erneut ausfuehren (gefahrlos wiederholbar)
lo kubehz register

Wenn der Cluster registriert ist, aber nicht in deinem Dashboard auftaucht, wurde er höchstwahrscheinlich noch nicht beansprucht — siehe Cluster beanspruchen.

Deregistrierung

Um deinen Cluster aus der kubehz-Registry zu entfernen:

lo kubehz deregister

Dies entfernt den Eintrag des Clusters bei kubehz. In deinem Cluster selbst wird nichts verändert; er funktioniert weiterhin unabhängig.

KUBEHZ_TOKEN

lo kubehz deregister und lo kubehz status senden optional die Umgebungsvariable KUBEHZ_TOKEN als Bearer-Token. Die Registrierung selbst benötigt niemals ein Token.

Nächste Schritte

• Cluster beanspruchen — Eigentum nachweisen und den Cluster deinem Konto zuordnen
• Dashboard — das Dashboard nutzen
• KubeOne — Provisioner-Leitfaden
• Hosted-Einrichtung — Alternative mit gehosteter Control Plane (Early Access)

---

Doku-Status

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