Registration

Register your self-hosted cluster with the kubehz platform for dashboard visibility.

Registration and claiming are the two halves of one handshake:

1. Register (CLI) — announce the cluster and its SSH key fingerprint to kubehz. The cluster is created as pending, attached to no account yet.
2. Claim (dashboard) — prove the SSH key belongs to your Hetzner Cloud account. The cluster attaches to your tenant. See Claiming.

Prerequisites

• A running Kubernetes cluster provisioned with lok8s
• kubectl configured and connected to your cluster
• A kubehz account — needed for the claim step, not for registration

Configuration

Add the kubehz block to your cluster.lok8s.yaml:

spec:
  kubehz:
    hosting: self
    access: registered       # or 'managed' for the management features (Supporter+)
    apiUrl: https://api.kubehz.cloud

apiUrl must be HTTPS — the CLI refuses plain-HTTP endpoints.

Access levels

Level	What kubehz sees	Cost
none	Nothing — no connection	Free
registered	Nodes, K8s version, component health, certificate expiry, uptime	Free (up to 2 clusters)
managed	Everything in registered, plus the management data behind healing policies, capacity watches, and desired-state management (upgrades/scaling)	Supporter tier or higher

Register

Registration runs automatically during lo provision (whenever access is not none). You can also run it manually at any time:

lo kubehz register

This sends a single request to POST /api/clusters/register on your configured apiUrl, containing exactly two fields: the cluster domain and the MD5 fingerprint of the cluster's SSH public key. No token or account is needed at this point, and nothing is installed into your cluster — the request is made by the CLI on your machine, not from inside the cluster.

On success the CLI prints what you need for the claim — a one-time claim code (the simplest path: paste it on the dashboard's Claim page — done) and the SSH key fingerprint for the alternative verification path:

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

The claim code works without any Hetzner token and is consumed on use — see Claiming for both paths.

The cluster is now pending: attached to no account and visible to nobody until you claim it. Unclaimed (pending) registrations are automatically deleted after 30 days — you can simply re-register at any time.

Why an MD5 fingerprint?

Ownership is verified against the SSH keys in your Hetzner Cloud account, and Hetzner exposes MD5 fingerprints — so kubehz uses the MD5 form. You can recompute it yourself at any time:

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

The fingerprint identifies your public key. It is not a secret and reveals nothing about your private key.

Claim your cluster

Registration alone attaches the cluster to nobody. Head to the dashboard and claim it — paste the claim code, or verify via SSH fingerprint + Hetzner token. See Claiming for the step-by-step guide.

Heartbeats

Cluster health in the dashboard comes from a lightweight CronJob named kubehz-heartbeat in the kubehz-system namespace. Every 5 minutes it POSTs to the kubehz API:

• Kubernetes version
• Node names, status, and roles
• Control-plane component health
• Certificate expiry

The agent runs with read-only RBAC and a hardened security context, and only makes outbound requests — the kubehz platform never connects into your cluster.

The agent is not installed automatically: its manifests ship with lok8s, and you apply them yourself — see the lok8s kubehz Platform guide for the install commands. Until it is installed, your cluster shows as Disconnected in the dashboard (registration and claiming still work without it).

Troubleshooting

# Registration status as seen by the CLI
lo kubehz status

# Is the heartbeat CronJob in place?
kubectl -n kubehz-system get cronjob kubehz-heartbeat

# Logs from recent heartbeat runs
kubectl -n kubehz-system logs -l app=kubehz-heartbeat

# Re-run registration (safe to repeat)
lo kubehz register

If the cluster is registered but missing from your dashboard, it is most likely still unclaimed — see Claiming.

Deregistration

To remove your cluster from the kubehz registry:

lo kubehz deregister

This removes the cluster's entry from kubehz. Nothing inside your cluster is modified, and it continues to work independently.

KUBEHZ_TOKEN

lo kubehz deregister and lo kubehz status optionally send the KUBEHZ_TOKEN environment variable as a bearer token. Registration itself never needs a token.

Next steps

• Claiming — prove ownership and attach the cluster to your account
• Dashboard — using the dashboard
• KubeOne — provisioner guide
• Hosted setup — hosted control plane alternative (early access)

---

Doc status

Aspect	Detail
State	active
Last reviewed	2026-07-10