Registrazione

Registra il tuo cluster self-hosted con la piattaforma kubehz per la visibilita nella dashboard.

Registrazione e rivendicazione sono le due meta di un unico handshake:

1. Registrazione (CLI) — annuncia il cluster e il fingerprint della sua chiave SSH a kubehz. Il cluster viene creato come pending (in attesa), non ancora collegato ad alcun account.
2. Rivendicazione (dashboard) — dimostri che la chiave SSH appartiene al tuo account Hetzner Cloud. Il cluster viene collegato al tuo tenant. Vedi Rivendicazione.

Prerequisiti

• Un cluster Kubernetes in esecuzione di cui e stato eseguito il provisioning con lok8s
• kubectl configurato e connesso al tuo cluster
• Un account kubehz — necessario per la rivendicazione, non per la registrazione

Configurazione

Aggiungi il blocco kubehz al tuo cluster.lok8s.yaml:

spec:
  kubehz:
    hosting: self
    access: registered       # oppure 'managed' per le funzionalita di gestione (Supporter+)
    apiUrl: https://api.kubehz.cloud

apiUrl deve essere HTTPS — la CLI rifiuta endpoint in HTTP semplice.

Livelli di accesso

Livello	Cosa vede kubehz	Costo
none	Nulla — nessuna connessione	Gratuito
registered	Nodi, versione K8s, stato dei componenti, scadenza dei certificati, uptime	Gratuito (fino a 2 cluster)
managed	Tutto quanto incluso in registered, piu i dati di gestione dietro le politiche di self-healing, il monitoraggio della capacita e la gestione dello stato desiderato (aggiornamenti/scaling)	Abbonamento Supporter o superiore

Registrazione

La registrazione avviene automaticamente durante lo provision (quando access non e none). Puoi anche eseguirla manualmente in qualsiasi momento:

lo kubehz register

Questo invia una singola richiesta a POST /api/clusters/register sull'apiUrl configurato, con esattamente due campi: il dominio del cluster e il fingerprint MD5 della chiave SSH pubblica del cluster. In questa fase non servono ne token ne account, e nulla viene installato nel tuo cluster — la richiesta parte dalla CLI sulla tua macchina, non dall'interno del cluster.

In caso di successo la CLI stampa ciò che ti serve per la rivendicazione — un codice di rivendicazione monouso (il percorso più semplice: incollalo nella pagina Rivendica della dashboard — fatto) e il fingerprint della chiave SSH per il percorso di verifica alternativo:

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

Il codice di rivendicazione funziona senza alcun token Hetzner e viene consumato all'uso — vedi Rivendicazione per entrambi i percorsi.

Il cluster ora e pending: non collegato ad alcun account e invisibile a chiunque finche non lo rivendichi. Le registrazioni non rivendicate (pending) vengono eliminate automaticamente dopo 30 giorni — puoi semplicemente registrare di nuovo il cluster in qualsiasi momento.

Perche un fingerprint MD5?

La proprieta viene verificata rispetto alle chiavi SSH nel tuo account Hetzner Cloud, e Hetzner espone fingerprint MD5 — per questo kubehz usa la forma MD5. Puoi ricalcolarlo tu stesso in qualsiasi momento:

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

Il fingerprint identifica la tua chiave pubblica. Non e un segreto e non rivela nulla della tua chiave privata.

Rivendica il tuo cluster

La sola registrazione non collega il cluster a nessuno. Vai nella dashboard e rivendicalo — incolla il codice di rivendicazione, oppure verifica tramite fingerprint SSH + token Hetzner. La guida passo passo e in Rivendicazione.

Heartbeat

Lo stato del cluster nella dashboard proviene da un CronJob leggero chiamato kubehz-heartbeat nel namespace kubehz-system. Ogni 5 minuti invia in POST all'API kubehz:

• Versione di Kubernetes
• Nomi, stato e ruoli dei nodi
• Stato dei componenti del control plane
• Scadenza dei certificati

L'agent gira con RBAC in sola lettura e un security context indurito, ed effettua solo richieste in uscita — la piattaforma kubehz non si connette mai verso l'interno del tuo cluster.

L'agent non viene installato automaticamente: i suoi manifest arrivano con lok8s e li applichi tu stesso — i comandi di installazione sono nella guida lok8s kubehz Platform. Finché non è installato, il tuo cluster appare come Disconnected nella dashboard (registrazione e rivendicazione funzionano anche senza).

Risoluzione dei problemi

# Stato della registrazione visto dalla CLI
lo kubehz status

# Il CronJob heartbeat e presente?
kubectl -n kubehz-system get cronjob kubehz-heartbeat

# Log delle ultime esecuzioni dell'heartbeat
kubectl -n kubehz-system logs -l app=kubehz-heartbeat

# Riesegui la registrazione (sicura da ripetere)
lo kubehz register

Se il cluster e registrato ma non compare nella tua dashboard, molto probabilmente non e ancora stato rivendicato — vedi Rivendicazione.

Annullamento della registrazione

Per rimuovere il tuo cluster dal registro kubehz:

lo kubehz deregister

Questo rimuove la voce del cluster da kubehz. Nulla viene modificato all'interno del tuo cluster, che continua a funzionare in modo indipendente.

KUBEHZ_TOKEN

lo kubehz deregister e lo kubehz status inviano opzionalmente la variabile d'ambiente KUBEHZ_TOKEN come bearer token. La registrazione in se non richiede mai un token.

Prossimi passi

• Rivendicazione — dimostra la proprieta e collega il cluster al tuo account
• Dashboard — usare la dashboard
• KubeOne — guida al provisioner
• Setup hosted — alternativa con control plane hosted (early access)

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-07-10