Registratie

Registreer je self-hosted cluster bij het kubehz-platform voor zichtbaarheid in het dashboard.

Registratie en claimen zijn de twee helften van een handshake:

1. Registreren (CLI) — meldt het cluster en de fingerprint van zijn SSH-sleutel aan bij kubehz. Het cluster wordt aangemaakt als pending (in afwachting), nog aan geen enkel account gekoppeld.
2. Claimen (dashboard) — je bewijst dat de SSH-sleutel bij jouw Hetzner Cloud-account hoort. Het cluster wordt aan je tenant gekoppeld. Zie Cluster claimen.

Vereisten

• Een draaiend Kubernetes-cluster, uitgerold met lok8s
• kubectl geconfigureerd en verbonden met je cluster
• Een kubehz-account — nodig voor het claimen, niet voor de registratie

Configuratie

Voeg het kubehz-blok toe aan je cluster.lok8s.yaml:

spec:
  kubehz:
    hosting: self
    access: registered       # of 'managed' voor de beheerfuncties (Supporter+)
    apiUrl: https://api.kubehz.cloud

apiUrl moet HTTPS zijn — de CLI weigert endpoints met onversleuteld HTTP.

Toegangsniveaus

Niveau	Wat kubehz ziet	Kosten
none	Niets — geen verbinding	Gratis
registered	Nodes, K8s-versie, componentstatus, certificaatverloop, uptime	Gratis (tot 2 clusters)
managed	Alles uit registered, plus de beheerdata achter healing-beleid, capaciteitsbewaking en beheer van de gewenste staat (upgrades/schalen)	Supporter-tier of hoger

Registreren

De registratie draait automatisch tijdens lo provision (zolang access niet none is). Je kunt haar ook op elk moment handmatig uitvoeren:

lo kubehz register

Dit stuurt een enkele request naar POST /api/clusters/register op de geconfigureerde apiUrl, met precies twee velden: het domein van het cluster en de MD5-fingerprint van de publieke SSH-sleutel van het cluster. Op dit punt is er geen token of account nodig, en er wordt niets in je cluster geïnstalleerd — de request komt van de CLI op jouw machine, niet vanuit het cluster.

Bij succes print de CLI wat je nodig hebt om te claimen — een eenmalige claimcode (het eenvoudigste pad: plak hem op de Claim-pagina van het dashboard — klaar) en de fingerprint van de SSH-sleutel voor het alternatieve verificatiepad:

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

De claimcode werkt zonder enige Hetzner-token en wordt verbruikt bij gebruik — zie Cluster claimen voor beide paden.

Het cluster is nu pending: aan geen enkel account gekoppeld en voor niemand zichtbaar totdat je het claimt. Niet-geclaimde (pending) registraties worden na 30 dagen automatisch verwijderd — je kunt op elk moment gewoon opnieuw registreren.

Waarom een MD5-fingerprint?

Eigendom wordt geverifieerd tegen de SSH-sleutels in je Hetzner Cloud-account, en Hetzner toont MD5-fingerprints — daarom gebruikt kubehz de MD5-vorm. Je kunt hem op elk moment zelf opnieuw berekenen:

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

De fingerprint identificeert je publieke sleutel. Het is geen geheim en verraadt niets over je private sleutel.

Claim je cluster

Registratie alleen koppelt het cluster aan niemand. Ga naar het dashboard en claim het — plak de claimcode, of verifieer via SSH-fingerprint + Hetzner-token. Zie Cluster claimen voor de stapsgewijze gids.

Heartbeats

De clusterstatus in het dashboard komt van een lichtgewicht CronJob met de naam kubehz-heartbeat in de namespace kubehz-system. Elke 5 minuten POST deze naar de kubehz-API:

• Kubernetes-versie
• Namen, status en rollen van nodes
• Status van de control plane-componenten
• Certificaatverloop

De agent draait met read-only RBAC en een gehardende security context, en doet uitsluitend uitgaande requests — het kubehz-platform maakt nooit verbinding je cluster in.

De agent wordt niet automatisch geïnstalleerd: de manifests komen mee met lok8s en je past ze zelf toe — de installatiecommando's staan in de lok8s kubehz Platform-gids. Tot de agent is geïnstalleerd toont het dashboard je cluster als Disconnected (registreren en claimen werken ook zonder).

Probleemoplossing

# Registratiestatus zoals de CLI die ziet
lo kubehz status

# Staat de heartbeat-CronJob er?
kubectl -n kubehz-system get cronjob kubehz-heartbeat

# Logs van recente heartbeat-runs
kubectl -n kubehz-system logs -l app=kubehz-heartbeat

# Registratie opnieuw uitvoeren (veilig te herhalen)
lo kubehz register

Is het cluster geregistreerd maar ontbreekt het in je dashboard, dan is het hoogstwaarschijnlijk nog niet geclaimd — zie Cluster claimen.

Deregistratie

Om je cluster uit het kubehz-register te verwijderen:

lo kubehz deregister

Dit verwijdert de vermelding van het cluster bij kubehz. Er wordt niets in je cluster gewijzigd; het blijft onafhankelijk werken.

KUBEHZ_TOKEN

lo kubehz deregister en lo kubehz status sturen optioneel de omgevingsvariabele KUBEHZ_TOKEN mee als bearer-token. De registratie zelf heeft nooit een token nodig.

Volgende stappen

• Cluster claimen — bewijs eigendom en koppel het cluster aan je account
• Dashboard — het dashboard gebruiken
• KubeOne — provisioner-gids
• Gehoste setup — alternatief met gehost control plane (early access)

---

Documentstatus

Aspect	Detail
Status	active
Laatst herzien	2026-07-10