Cluster claimen

Claimen bewijst dat een geregistreerd cluster van jou is en koppelt het aan je kubehz-account.

Registratie kondigt een cluster alleen maar aan: het wordt aangemaakt met de status Creating en is van niemand. Iedereen zou elk willekeurig domein kunnen aanmelden, dus eigendom vraagt om bewijs. De pagina Claim in het dashboard biedt drie bewijzen, en een vierde pad slaat het claimen helemaal over:

Bewijs	Wat het nodig heeft	Wanneer je het gebruikt
Claimsleutel (tabblad fingerprint)	De fingerprint die lo kubehz register heeft geprint.	Het gebruikelijke geval: je hebt uitgerold met HCLOUD_TOKEN in je shell.
Claimcode	De geïnstalleerde heartbeat-agent.	Elk cluster, elke provider; er komt geen Hetzner-project aan te pas.
Via agent (nonce)	De geïnstalleerde heartbeat-agent, plus één lo-commando.	Je zit toch al in de CLI en wilt dat het dashboard toekijkt hoe de agent bevestigt.
Directe toewijzing	KUBEHZ_TOKEN in je shell bij de registratie.	CI en automatisering. Het cluster registreert direct op je tenant; er valt niets te claimen.

Optie 1: de claimsleutel (gebruikelijk)

Staat HCLOUD_TOKEN ingesteld, dan vraagt lo kubehz register de api om een claimsleutel en uploadt de publieke helft ervan naar je Hetzner Cloud-project onder de naam kubehz-claim-<domain>. Alleen de eigenaar van het project kan die sleutel hebben, dus zijn fingerprint is het bewijs. Er wordt nergens een token geplakt.

1. Open het dashboard op app.kubehz.cloud en log in
2. Ga naar de pagina Claim en kies het tabblad SSH-fingerprint
3. Plak de fingerprint uit de CLI-uitvoer: MD5:aa:bb:cc:… of de kale vorm aa:bb:cc:… (beide worden geaccepteerd)
4. Klik op Cluster claimen

kubehz vergelijkt de fingerprint met de claimsleutel die het voor dat cluster heeft aangemaakt. Bij succes wordt het cluster aan je tenant gekoppeld en opent zijn detailpagina. Dezelfde controle is ook vanuit een script beschikbaar:

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"}'

Ben je de CLI-uitvoer kwijt, dan staat de fingerprint in de Hetzner Console onder Security → SSH keys. lo kubehz register opnieuw uitvoeren roteert de sleutel en print de nieuwe fingerprint.

Legacy: de provisioning-sleutel

Een cluster dat zonder HCLOUD_TOKEN is geregistreerd, wordt aangemeld met de MD5-fingerprint van de SSH-sleutel in je providerbeschrijving (sshPublicKey). Bestaat die sleutel in je Hetzner Cloud-project, dan accepteert hetzelfde fingerprint-tabblad hem. Je kunt hem op elk moment opnieuw berekenen:

# de sleutel die sshPublicKey in je providerbeschrijving noemt
ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub

Optie 2: de claimcode

Vereist de geïnstalleerde heartbeat-agent: die maakt de code bij de eerste run. Drukt lo kubehz claim-code niets af, dan heeft de agent nog niet gedraaid.

De agent maakt bij zijn eerste run een eenmalige claimcode aan in je cluster. Print hem met lo kubehz claim-code (gericht op dat cluster). Daarna is claimen één keer plakken:

1. Open het dashboard op app.kubehz.cloud en log in
2. Ga naar de pagina Claim en kies het tabblad Claimcode
3. Plak de claimcode, klaar. Het cluster wordt aan je tenant gekoppeld en zijn detailpagina opent.

Een paar eigenschappen die het weten waard zijn:

• Provider-agnostisch: de code werkt zonder enig Hetzner-project, voor elk cluster.
• Verbruikt bij gebruik: een code claimt precies één cluster, één keer.
• Geen orakel: een verkeerde, verlopen of al gebruikte code geeft steeds hetzelfde antwoord “not found”; de claimpagina onthult niet welke van de drie het was. Werkt je code niet meer, val dan terug op de claimsleutel hierboven.
• Eenmalig aangemaakt: de agent genereert de code bij zijn eerste run en roteert hem nooit; lo kubehz claim-code print dezelfde code tot hij gebruikt is.

Optie 3: via agent (nonce)

Vereist ook de heartbeat-agent. Hier maakt het dashboard het geheim aan en stuurt je cluster het terug:

1. Kies op de pagina Claim de optie Via agent. Het dashboard maakt een challenge-nonce aan (khzn_…) en wacht.

2. Zet hem met de CLI in je cluster:

   lo kubehz claim --nonce khzn_...

3. De agent stuurt de nonce terug in zijn volgende heartbeat. Het dashboard ziet dat en koppelt het cluster aan je tenant.

De nonce is eenmalig en kort geldig; loopt de pagina af, maak dan een nieuwe aan.

Optie 4: helemaal niet claimen

Met KUBEHZ_TOKEN in je shell (een clusters:write-API-token uit het dashboard, Toegang → API-tokens) registreert lo kubehz register het cluster direct op je tenant. Het verschijnt meteen in je clusterlijst; er is geen claimstap. Dit is het pad voor CI. Bewaar het token in een secret store, nooit in de spec.

Beveiligingsnotities

• Een fingerprint is publieke informatie: hij identificeert een publieke sleutel, maar kan zich niet als jou voordoen. De claimsleutel werkt omdat alleen jouw Hetzner-project de sleutel kan hebben die kubehz voor je cluster heeft aangemaakt.
• Het platform maakt nooit verbinding je cluster in. Statusdata stroomt uitsluitend naar buiten, via de heartbeat-agent.
• Mislukt de verificatie, dan meldt het dashboard dat (“Claim verification failed”) en wordt er niets gekoppeld.

Na het claimen

• Het cluster verlaat de status Creating en verschijnt direct in je clusterlijst
• Statusdetails (nodes, componentstatus, certificaatverloop) vullen zich met binnenkomende heartbeats, elke 5 minuten ververst
• Connected betekent dat er in de laatste 15 minuten een heartbeat is ontvangen; het dashboard leidt uit de heartbeat-historie ook een uptime over 30 dagen af

Probleemoplossing

Symptoom	Oplossing
Fingerprint niet geaccepteerd	Gebruik de fingerprint die lo kubehz register heeft geprint, of lees hem af in de Hetzner Console (Security → SSH keys, sleutel kubehz-claim-<domain>). Voer lo kubehz register opnieuw uit met HCLOUD_TOKEN ingesteld om een verse sleutel aan te maken
Claimcode “not found”	Codes zijn eenmalig en verlopen samen met de registratie. Gebruik de claimsleutel
De pagina “Via agent” blijft wachten	De agent heeft niet geklopt sinds je de nonce hebt geplaatst. Controleer kubectl -n kubehz-system get cronjob kubehz-heartbeat en maak daarna een nieuwe nonce aan
Sleutel ontbreekt bij Hetzner	lo kubehz register kon de claimsleutel niet uploaden. Controleer of HCLOUD_TOKEN lees- en schrijfrechten op het project heeft en voer het opnieuw uit
Cluster nog niet geregistreerd	Voer eerst lo kubehz register uit. Zie Registratie

Volgende stappen

• Dashboard: wat je na het claimen kunt zien en doen
• Registratie: de CLI-helft van de handshake
• Prijzen: wat de gratis tier dekt

---

Documentstatus

Aspect	Detail
Status	active
Laatst herzien	2026-09-05