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:

Registrieren (CLI): meldet den Cluster bei kubehz an. Der Cluster wird mit dem Status Creating angelegt und ist noch keinem Konto zugeordnet.
Beanspruchen (Dashboard): Du weist nach, dass der Cluster dir gehört. Der übliche Nachweis ist der Claim-Schlüssel, den lo in dein Hetzner-Cloud-Projekt hochlädt; ein Claim-Code oder eine Nonce, die der Agent zurückmeldet, funktionieren ebenfalls. 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:

yaml

spec:
  kubehz:
    # self | hosted | shared
    hosting: self
    # 'managed' schaltet die Verwaltungsfunktionen frei (Supporter+)
    access: registered
    # cronjob (schreibgeschützter Heartbeat) | operator (Managed-Stufe, Live-Ansicht)
    agent: cronjob
    apiUrl: https://api.kubehz.cloud

apiUrl muss HTTPS sein: Die CLI lehnt Endpunkte mit unverschlüsseltem HTTP ab. Die optionalen Schlüssel (connectHcloudToken, upgrades, maintenanceWindow, space) stehen unter Erster Cluster.

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:

bash

lo kubehz register

Die CLI auf deinem Rechner stellt die Anfrage an POST /api/clusters/register auf der konfigurierten apiUrl; in deinem Cluster wird nichts installiert. Was sie sendet, hängt davon ab, was in deiner Shell gesetzt ist:

In deiner Shell	Was passiert	So beanspruchst du
`HCLOUD_TOKEN` (der Normalfall nach `lo provision`)	Die API stellt einen Claim-Schlüssel aus, und `lo` lädt dessen öffentliche Hälfte als `kubehz-claim-<domain>` in dein Hetzner-Cloud-Projekt hoch. Ein erneuter Lauf rotiert den Schlüssel.	Füge den Fingerprint des Schlüssels auf der Claim-Seite ein. Kein Token verlässt deinen Rechner.
`KUBEHZ_TOKEN` (ein `clusters:write`-API-Token aus dem Dashboard, Zugriff → API-Tokens)	Der Cluster wird direkt auf deinem Tenant registriert. Mit `connectHcloudToken: true` in der Spec übergibt `lo` der Plattform zusätzlich deinen Hetzner-Token, ausschließlich über HTTPS.	Nichts zu beanspruchen: Der Cluster gehört dir bereits.
keins von beiden	`lo` sendet die Domain plus den MD5-Fingerprint des SSH-Schlüssels aus deinem Provider-Deskriptor.	Der Claim-Code vom Heartbeat-Agent, oder der Fingerprint, falls dieser Schlüssel in deinem Hetzner-Projekt liegt.

Auf dem üblichen Weg gibt die CLI den Fingerprint aus, mit dem du beanspruchst:

kubehz: cluster 'example.com' registered (pending). Claim key 'kubehz-claim-example.com' uploaded to your Hetzner Cloud account.
kubehz: claim it with the fingerprint ALONE — dashboard /claim (SSH fingerprint tab), or:
  curl -X POST https://api.kubehz.cloud/api/claims/verify -H 'Authorization: Bearer <khzt_ token (clusters:write)>' \
       -H 'Content-Type: application/json' -d '{"fingerprint":"..."}'
  fingerprint: aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99   (also visible in Hetzner Console -> Security -> SSH keys)

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

Der Cluster hat jetzt den Status Creating: keinem Konto zugeordnet und für niemanden sichtbar, bis du ihn beanspruchst. Nicht beanspruchte Registrierungen werden nach 30 Tagen automatisch gelöscht; du kannst jederzeit einfach neu registrieren.

Cluster beanspruchen

Die Registrierung allein ordnet den Cluster niemandem zu. Geh ins Dashboard und beanspruche ihn: Füge den Fingerprint des Claim-Schlüssels ein, oder nutze einen der anderen Nachweise. Die Schritt-für-Schritt-Anleitung findest du unter Cluster beanspruchen.

Heartbeats

Der Cluster-Status im Dashboard stammt von einem Agent im Cluster, im Namespace kubehz-system. Mit agent: cronjob (dem Standard) ist das ein leichtgewichtiger CronJob namens kubehz-heartbeat, der alle 5 Minuten per POST an die kubehz-API sendet:

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.

Installiere ihn mit der CLI. Sie rendert die Agent-Manifeste, die mit lok8s ausgeliefert werden (API-URL, deine Domain und der Heartbeat-Besitzer werden für dich eingetragen), und wendet sie mit deiner kubeconfig an:

bash

# erst die gerenderten Manifeste ansehen, nichts anwenden
lo kubehz deploy --dry-run

lo kubehz deploy

Beim ersten Lauf legt der Agent sein Identity-Secret an, registriert sich selbst und beginnt zu senden. Alle Optionen: der lok8s kubehz-Platform-Guide. Bis zur Installation zeigt das Dashboard deinen Cluster als Disconnected an (Registrierung und Beanspruchen funktionieren auch ohne den Agent).

Operator-Modus (Managed-Stufe)

Mit agent: operator installiert lo kubehz deploy den dauerhaft laufenden kubehz-agent neben dem CronJob und übergibt ihm den Heartbeat. Er beobachtet den Cluster und sendet eine Schema-2-Nutzlast, sobald sich etwas ändert. Alles, was er sendet, sind Metadaten; Workload-Namen und -Inhalte verlassen den Cluster nur, wenn du das ausdrücklich aktivierst.

Feld	Was es enthält
`schema`, `clusterId`, `timestamp`	`2`, deine Cluster-ID, der Zeitpunkt des Heartbeats.
`agent`	`version` und `mode` (`operator`) des Agents.
`kubernetes.version`	Die Version des API-Servers.
`nodes[]`	Pro Node: `name`, `status`, `ready`, `roles`, `instanceType`, `kubeletVersion` und `capacity` (`cpu`, `memory`).
`components[]`	`name` und `status` der Control-Plane-Komponenten.
`workloads.pods`	Pod-Zahlen nach Phase: `total`, `running`, `pending`, `failed`, `succeeded`, `unknown`. `deployments` (`total`, `unavailable`), wenn der Apps-Informer aktiv ist.
`events[]`	Aktuelle Warning-Events: `reason`, `kind`, `count`, `lastSeen`.
`actions[]`	Fortschritt der Desired-State-Aktionen, die der Agent ausgeführt hat: `type` (`scale`, `upgrade`, `heal`), `target`, `status`, `detail`, `revision`.
`machineIssues[]`	Fehler des Machine-Controllers: `pool`, `machine`, `reason`, `message`, `since`.
`inventory`	Was lok8s bereitgestellt hat, aus dem `ClusterInventory`-Objekt, das dein eigenes `lo` geschrieben hat: `lok8sVersion`, `kind`, `provider`, `kubernetesVersion`, `specHash`, `renderedAt` und `addons[]` (`name`, `chartVersion`, `appVersion`, `category`, `source`). Niemals Chart-Values oder Zugangsdaten.
`pools[]`, `desired`, `certificates`	Reserviert für die beobachteten Worker-Pools, die Bestätigung des gewünschten Zustands und den Zertifikatsablauf.

Nur per Opt-in. Namespace-Namen werden standardmäßig nicht gemeldet. Setze KUBEHZ_REPORT_NAMESPACES=true am Agent, um workloads.pods.byNamespace (Pod-Zahlen pro Namespace) sowie die Felder namespace und note (die Event-Nachricht) an Events zu ergänzen. Bleibt die Variable ungesetzt, fehlen diese Schlüssel in jedem Heartbeat.

Der AVV bezeichnet diese Felder als Heartbeat-Metadaten.

Fehlerbehebung

bash

# Registrierungsstatus aus Sicht der CLI (braucht KUBEHZ_TOKEN)
lo kubehz status

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

# Logs der letzten Heartbeat-Läufe
kubectl -n kubehz-system logs -l app=kubehz-heartbeat

# Registrierung erneut ausführen (gefahrlos wiederholbar)
lo kubehz register

# Der Agent hat sein Identity-Secret verloren (Namespace neu angelegt, Cluster wiederhergestellt):
# ein neues für denselben registrierten Cluster ausstellen (braucht KUBEHZ_TOKEN)
lo kubehz re-enroll

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:

bash

lo kubehz deregister

Dies entfernt den Eintrag des Clusters bei kubehz und zieht den Claim-Schlüssel in deinem Hetzner-Projekt zurück. In deinem Cluster selbst wird nichts verändert; er funktioniert weiterhin unabhängig. Um auch den Agent zu entfernen, lösche den Namespace kubehz-system und sein clusterweites RBAC (siehe Migration).

KUBEHZ_TOKEN

lo kubehz deregister, lo kubehz status und lo kubehz re-enroll lesen die Cluster-Registry des Tenants und benötigen deshalb KUBEHZ_TOKEN: ein clusters:write-API-Token, das du im Dashboard unter Zugriff → API-Tokens ausstellst. 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

Doku-Status

Aspekt	Detail
Zustand	aktiv
Zuletzt geprüft	2026-09-05

Registrierung ​

Voraussetzungen ​

Konfiguration ​

Zugriffsebenen ​

Registrieren ​

Cluster beanspruchen ​

Heartbeats ​

Operator-Modus (Managed-Stufe) ​

Fehlerbehebung ​

Deregistrierung ​

Nächste Schritte ​

Doku-Status ​

Registrierung

Voraussetzungen

Konfiguration

Zugriffsebenen

Registrieren

Cluster beanspruchen

Heartbeats

Operator-Modus (Managed-Stufe)

Fehlerbehebung

Deregistrierung

Nächste Schritte

Doku-Status