Registrazione

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

Registrazione e rivendicazione sono le due metà di un unico handshake:

1. Registrazione (CLI): annuncia il cluster a kubehz. Il cluster viene creato con lo stato Creating, non ancora collegato ad alcun account.
2. Rivendicazione (dashboard): dimostri che il cluster è tuo. La prova abituale è la chiave di rivendicazione che lo carica nel tuo progetto Hetzner Cloud; funzionano anche un codice di rivendicazione o un nonce che l’agent restituisce. Il cluster viene collegato al tuo tenant. Vedi Rivendicazione.

Prerequisiti

• Un cluster Kubernetes in esecuzione di cui è 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:
    # self | hosted | shared
    hosting: self
    # 'managed' sblocca le funzionalità di gestione (Supporter+)
    access: registered
    # cronjob (heartbeat in sola lettura) | operator (tier managed, vista live)
    agent: cronjob
    apiUrl: https://api.kubehz.cloud

apiUrl deve essere HTTPS: la CLI rifiuta endpoint in HTTP semplice. Le chiavi facoltative (connectHcloudToken, upgrades, maintenanceWindow, space) sono elencate in Primo cluster.

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, più i dati di gestione dietro le politiche di self-healing, il monitoraggio della capacità e la gestione dello stato desiderato (aggiornamenti/scaling)	Abbonamento Supporter o superiore

Registrazione

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

lo kubehz register

La richiesta a POST /api/clusters/register sull’apiUrl configurato parte dalla CLI sulla tua macchina; nulla viene installato nel tuo cluster. Cosa invia dipende da cosa c’è nella tua shell:

Nella tua shell	Cosa accade	Come rivendichi
HCLOUD_TOKEN (il caso abituale dopo lo provision)	L’api genera una chiave di rivendicazione e lo carica la sua metà pubblica nel tuo progetto Hetzner Cloud come kubehz-claim-<domain>. Rieseguire il comando ruota la chiave.	Incolla il fingerprint della chiave nella pagina di rivendicazione. Nessun token lascia la tua macchina.
KUBEHZ_TOKEN (un token API clusters:write dalla dashboard, Accesso → Token API)	Il cluster viene registrato direttamente sul tuo tenant. Con connectHcloudToken: true nello spec, lo consegna alla piattaforma anche il tuo token Hetzner, solo via HTTPS.	Niente da rivendicare: il cluster è già tuo.
nessuno dei due	lo invia il dominio più il fingerprint MD5 della chiave SSH nel tuo descrittore del provider.	Il codice di rivendicazione dell’agent heartbeat, oppure il fingerprint se quella chiave si trova nel tuo progetto Hetzner.

Nel caso abituale la CLI stampa il fingerprint con cui rivendicare:

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)

Il fingerprint identifica una chiave pubblica. Non è un segreto e non rivela nulla delle tue chiavi private.

Il cluster ora ha lo stato Creating: non collegato ad alcun account e invisibile a chiunque finché non lo rivendichi. Le registrazioni non rivendicate vengono eliminate automaticamente dopo 30 giorni; puoi semplicemente registrare di nuovo il cluster in qualsiasi momento.

Rivendica il tuo cluster

La sola registrazione non collega il cluster a nessuno. Vai nella dashboard e rivendicalo: incolla il fingerprint della chiave di rivendicazione, oppure usa una delle altre prove. La guida passo passo è in Rivendicazione.

Heartbeat

Lo stato del cluster nella dashboard proviene da un agent nel cluster, nel namespace kubehz-system. Con agent: cronjob (il default) è un CronJob leggero chiamato kubehz-heartbeat che 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.

Installalo con la CLI. Renderizza i manifest dell’agent forniti con lok8s (l’URL dell’API, il tuo dominio e il proprietario dell’heartbeat vengono compilati per te) e li applica con il tuo kubeconfig:

# guarda prima i manifest renderizzati, senza applicare nulla
lo kubehz deploy --dry-run

lo kubehz deploy

Al primo avvio l’agent crea il proprio Secret di identità, si registra da solo e inizia a battere. Tutte le opzioni: la guida lok8s kubehz Platform. Finché non è installato, il tuo cluster appare come Disconnected nella dashboard (registrazione e rivendicazione funzionano anche senza).

Modalità operator (tier managed)

Con agent: operator, lo kubehz deploy installa il kubehz-agent a lunga esecuzione accanto al CronJob e gli affida l’heartbeat. Osserva il cluster e invia un payload schema-2 ogni volta che qualcosa cambia. Tutto ciò che invia sono metadati; nomi e contenuti dei workload non lasciano mai il cluster a meno che tu non scelga di attivarlo.

Campo	Cosa contiene
schema, clusterId, timestamp	2, l’id del tuo cluster, l’ora del battito.
agent	version e mode (operator) dell’agent.
kubernetes.version	La versione dell’API server.
nodes[]	Per nodo: name, status, ready, roles, instanceType, kubeletVersion e capacity (cpu, memory).
components[]	name e status dei componenti del control plane.
workloads.pods	Conteggio dei pod per fase: total, running, pending, failed, succeeded, unknown. deployments (total, unavailable) quando l’informer delle app è attivo.
events[]	Eventi Warning recenti: reason, kind, count, lastSeen.
actions[]	Avanzamento delle azioni di stato desiderato eseguite dall’agent: type (scale, upgrade, heal), target, status, detail, revision.
machineIssues[]	Errori del machine-controller: pool, machine, reason, message, since.
inventory	Cosa ha deployato lok8s, dall’oggetto ClusterInventory scritto dal tuo lo: lok8sVersion, kind, provider, kubernetesVersion, specHash, renderedAt e addons[] (name, chartVersion, appVersion, category, source). Mai valori dei chart o credenziali.
pools[], desired, certificates	Riservati ai worker pool osservati, alla conferma dello stato desiderato e alla scadenza dei certificati.

Solo opt-in. I nomi dei namespace non vengono riportati per default. Imposta KUBEHZ_REPORT_NAMESPACES=true sull’agent per aggiungere workloads.pods.byNamespace (conteggio dei pod per namespace) e i campi namespace e note (il messaggio dell’evento) sugli eventi. Se non la imposti, quelle chiavi sono assenti da ogni battito.

Il DPA chiama questi campi metadati dell’heartbeat.

Risoluzione dei problemi

# Stato della registrazione visto dalla CLI (richiede KUBEHZ_TOKEN)
lo kubehz status

# Il CronJob heartbeat è 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

# L'agent ha perso il suo Secret di identità (namespace ricreato, cluster ripristinato):
# generane uno nuovo per lo stesso cluster registrato (richiede KUBEHZ_TOKEN)
lo kubehz re-enroll

Se il cluster è registrato ma non compare nella tua dashboard, molto probabilmente non è 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 e ritira la chiave di rivendicazione dal tuo progetto Hetzner. Nulla viene modificato all’interno del tuo cluster, che continua a funzionare in modo indipendente. Per rimuovere anche l’agent, elimina il namespace kubehz-system e il suo RBAC a livello di cluster (vedi Migrazione).

KUBEHZ_TOKEN

lo kubehz deregister, lo kubehz status e lo kubehz re-enroll leggono il registro dei cluster del tenant, quindi richiedono KUBEHZ_TOKEN: un token API clusters:write generato nella dashboard in Accesso → Token API. La registrazione in sé non richiede mai un token.

Prossimi passi

• Rivendicazione: dimostra la proprietà e collega il cluster al tuo account
• Dashboard: usare la dashboard
• KubeOne: guida al provisioner
• Setup hosted: alternativa con control plane hosted

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-09-05