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 aan bij kubehz. Het cluster wordt aangemaakt met de status Creating, nog aan geen enkel account gekoppeld.
2. Claimen (dashboard): je bewijst dat het cluster van jou is. Het gebruikelijke bewijs is de claimsleutel die lo naar je Hetzner Cloud-project uploadt; een claimcode of een nonce die de agent terugstuurt werken ook. 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:
    # self | hosted | shared
    hosting: self
    # 'managed' ontgrendelt de beheerfuncties (Supporter+)
    access: registered
    # cronjob (alleen-lezen heartbeat) | operator (managed-tier, live weergave)
    agent: cronjob
    apiUrl: https://api.kubehz.cloud

apiUrl moet HTTPS zijn: de CLI weigert endpoints met onversleuteld HTTP. De optionele sleutels (connectHcloudToken, upgrades, maintenanceWindow, space) staan in Eerste cluster.

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

De CLI op jouw machine stuurt de request naar POST /api/clusters/register op de geconfigureerde apiUrl; er wordt niets in je cluster geïnstalleerd. Wat hij meestuurt, hangt af van wat er in je shell staat:

In je shell	Wat er gebeurt	Hoe je claimt
HCLOUD_TOKEN (het gebruikelijke geval na lo provision)	De api maakt een claimsleutel aan en lo uploadt de publieke helft naar je Hetzner Cloud-project als kubehz-claim-<domain>. Opnieuw uitvoeren roteert de sleutel.	Plak de fingerprint van de sleutel op de claimpagina. Er verlaat geen token je machine.
KUBEHZ_TOKEN (een clusters:write-API-token uit het dashboard, Toegang → API-tokens)	Het cluster wordt direct op je tenant geregistreerd. Met connectHcloudToken: true in de spec geeft lo het platform ook je Hetzner-token, alleen over HTTPS.	Niets te claimen: het cluster is al van jou.
geen van beide	lo stuurt het domein plus de MD5-fingerprint van de SSH-sleutel in je providerbeschrijving.	De claimcode van de heartbeat-agent, of de fingerprint als die sleutel in je Hetzner-project staat.

Op het gebruikelijke pad print de CLI de fingerprint waarmee je claimt:

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)

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

Het cluster heeft nu de status Creating: aan geen enkel account gekoppeld en voor niemand zichtbaar totdat je het claimt. Niet-geclaimde registraties worden na 30 dagen automatisch verwijderd; je kunt op elk moment gewoon opnieuw registreren.

Claim je cluster

Registratie alleen koppelt het cluster aan niemand. Ga naar het dashboard en claim het: plak de fingerprint van de claimsleutel, of gebruik een van de andere bewijzen. Zie Cluster claimen voor de stapsgewijze gids.

Heartbeats

De clusterstatus in het dashboard komt van een agent in het cluster, in de namespace kubehz-system. Met agent: cronjob (de standaard) is dat een lichtgewicht CronJob met de naam kubehz-heartbeat, die elke 5 minuten naar de kubehz-API POST:

• 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.

Installeer hem met de CLI. Die rendert de agent-manifests die met lok8s meekomen (de API-URL, je domein en de eigenaar van de heartbeat worden voor je ingevuld) en past ze toe met je kubeconfig:

# bekijk eerst de gerenderde manifests, pas niets toe
lo kubehz deploy --dry-run

lo kubehz deploy

Bij de eerste run maakt de agent zijn identity-Secret aan, registreert zichzelf en begint te kloppen. Alle opties: de lok8s kubehz Platform-gids. Tot de agent is geïnstalleerd toont het dashboard je cluster als Disconnected (registreren en claimen werken ook zonder).

Operator-modus (managed-tier)

Met agent: operator installeert lo kubehz deploy de langlopende kubehz-agent naast de CronJob en draagt de heartbeat aan hem over. Hij bewaakt het cluster en stuurt een schema-2-payload zodra er iets verandert. Alles wat hij stuurt is metadata; namen en inhoud van workloads verlaten het cluster nooit, tenzij je daar zelf voor kiest.

Veld	Wat het bevat
schema, clusterId, timestamp	2, je cluster-id, het tijdstip van de heartbeat.
agent	De version en mode (operator) van de agent.
kubernetes.version	De versie van de API-server.
nodes[]	Per node: name, status, ready, roles, instanceType, kubeletVersion en capacity (cpu, memory).
components[]	name en status van elk control plane-component.
workloads.pods	Aantal pods per fase: total, running, pending, failed, succeeded, unknown. deployments (total, unavailable) als de apps-informer aanstaat.
events[]	Recente Warning-events: reason, kind, count, lastSeen.
actions[]	Voortgang van desired-state-acties die de agent heeft uitgevoerd: type (scale, upgrade, heal), target, status, detail, revision.
machineIssues[]	Fouten van de machine-controller: pool, machine, reason, message, since.
inventory	Wat lok8s heeft uitgerold, uit het ClusterInventory-object dat je eigen lo heeft geschreven: lok8sVersion, kind, provider, kubernetesVersion, specHash, renderedAt en addons[] (name, chartVersion, appVersion, category, source). Nooit chart-values of credentials.
pools[], desired, certificates	Gereserveerd voor de waargenomen worker pools, de bevestiging van de gewenste staat en het certificaatverloop.

Alleen op verzoek. Namespace-namen worden standaard niet gerapporteerd. Zet KUBEHZ_REPORT_NAMESPACES=true op de agent om workloads.pods.byNamespace (aantal pods per namespace) en de velden namespace en note (het event-bericht) aan events toe te voegen. Laat je dit ongezet, dan ontbreken die sleutels in elke heartbeat.

De DPA noemt deze velden heartbeat-metadata.

Probleemoplossing

# Registratiestatus zoals de CLI die ziet (vereist KUBEHZ_TOKEN)
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

# De agent is zijn identity-Secret kwijt (namespace opnieuw aangemaakt, cluster hersteld):
# maak een nieuw aan voor hetzelfde geregistreerde cluster (vereist KUBEHZ_TOKEN)
lo kubehz re-enroll

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 en trekt de claimsleutel in je Hetzner-project in. Er wordt niets in je cluster gewijzigd; het blijft onafhankelijk werken. Wil je ook de agent verwijderen, verwijder dan de namespace kubehz-system en de clusterbrede RBAC ervan (zie Migratie).

KUBEHZ_TOKEN

lo kubehz deregister, lo kubehz status en lo kubehz re-enroll lezen het clusterregister van de tenant en vereisen daarom KUBEHZ_TOKEN: een clusters:write-API-token dat je in het dashboard aanmaakt onder Toegang → API-tokens. 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

---

Documentstatus

Aspect	Detail
Status	active
Laatst herzien	2026-09-05