Rivendicazione

La rivendicazione dimostra che un cluster registrato è tuo e lo collega al tuo account kubehz.

La registrazione si limita ad annunciare un cluster: viene creato con lo stato Creating, senza proprietario. Chiunque potrebbe annunciare qualsiasi dominio, quindi la proprietà richiede una prova. La pagina Rivendica (Claim) della dashboard offre tre prove, e un quarto percorso salta del tutto la rivendicazione:

Prova	Cosa serve	Quando usarla
Chiave di rivendicazione (scheda fingerprint)	Il fingerprint stampato da lo kubehz register.	Il caso abituale: hai fatto il provisioning con HCLOUD_TOKEN nella shell.
Codice di rivendicazione	L’agent heartbeat installato.	Qualsiasi cluster, qualsiasi provider; nessun progetto Hetzner coinvolto.
Tramite agent (nonce)	L’agent heartbeat installato, più un comando lo.	Sei comunque alla CLI e vuoi che la dashboard osservi la conferma dell’agent.
Attribuzione diretta	KUBEHZ_TOKEN nella shell alla registrazione.	CI e automazione. Il cluster viene registrato direttamente sul tuo tenant; non c’è nulla da rivendicare.

Opzione 1: la chiave di rivendicazione (abituale)

Quando HCLOUD_TOKEN è impostato, lo kubehz register chiede all’api una chiave di rivendicazione e carica la sua metà pubblica nel tuo progetto Hetzner Cloud con il nome kubehz-claim-<domain>. Solo il proprietario del progetto può avere quella chiave, quindi il suo fingerprint è la prova. Nessun token viene incollato da nessuna parte.

1. Apri la dashboard su app.kubehz.cloud e accedi
2. Vai alla pagina Rivendica (Claim) e scegli la scheda Fingerprint SSH
3. Incolla il fingerprint dall’output della CLI: MD5:aa:bb:cc:… oppure la forma semplice aa:bb:cc:… (entrambe accettate)
4. Clicca Rivendica Cluster

kubehz confronta il fingerprint con la chiave di rivendicazione che ha generato per quel cluster. In caso di successo il cluster viene collegato al tuo tenant e si apre la sua pagina di dettaglio. Lo stesso controllo è disponibile da uno script:

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

Se perdi l’output della CLI, il fingerprint è elencato nella Hetzner Console sotto Security → SSH keys. Rieseguire lo kubehz register ruota la chiave e stampa il nuovo fingerprint.

Legacy: la chiave di provisioning

Un cluster registrato senza HCLOUD_TOKEN viene annunciato con il fingerprint MD5 della chiave SSH nel tuo descrittore del provider (sshPublicKey). Se quella chiave esiste nel tuo progetto Hetzner Cloud, la stessa scheda fingerprint la accetta. Ricalcolalo in qualsiasi momento:

# la chiave indicata da sshPublicKey nel tuo descrittore del provider
ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub

Opzione 2: il codice di rivendicazione

Richiede l’agent heartbeat installato: genera il codice al primo avvio. Se lo kubehz claim-code non stampa nulla, l’agent non è ancora partito.

L’agent genera un codice di rivendicazione monouso dentro il tuo cluster alla prima esecuzione. Stampalo con lo kubehz claim-code (puntato a quel cluster). Poi rivendicare è un solo incolla:

1. Apri la dashboard su app.kubehz.cloud e accedi
2. Vai alla pagina Rivendica (Claim) e scegli la scheda Codice di rivendicazione
3. Incolla il codice di rivendicazione, ed è fatto. Il cluster viene collegato al tuo tenant e si apre la sua pagina di dettaglio.

Alcune proprietà che vale la pena conoscere:

• Indipendente dal provider: il codice funziona senza alcun progetto Hetzner, per qualsiasi cluster.
• Consumato all’uso: un codice rivendica esattamente un cluster, una sola volta.
• Nessun oracolo: un codice sbagliato, scaduto o già usato restituisce sempre la stessa risposta “not found”; la pagina di rivendicazione non rivela quale dei tre fosse. Se il tuo codice non funziona più, ripiega sulla chiave di rivendicazione qui sopra.
• Generato una volta sola: l’agent crea il codice alla prima esecuzione e non lo ruota mai; lo kubehz claim-code stampa sempre lo stesso codice finché non viene usato.

Opzione 3: tramite agent (nonce)

Richiede anch’essa l’agent heartbeat. Qui è la dashboard a generare il segreto e il tuo cluster lo restituisce:

1. Nella pagina Rivendica scegli Tramite agent. La dashboard genera un nonce di sfida (khzn_…) e attende.

2. Mettilo nel tuo cluster con la CLI:

   lo kubehz claim --nonce khzn_...

3. L’agent restituisce il nonce nel suo heartbeat successivo. La dashboard lo vede e collega il cluster al tuo tenant.

Il nonce è monouso e di breve durata; se la pagina va in timeout, generane uno nuovo.

Opzione 4: nessuna rivendicazione

Con KUBEHZ_TOKEN nella shell (un token API clusters:write dalla dashboard, Accesso → Token API), lo kubehz register registra il cluster direttamente sul tuo tenant. Compare subito nella tua lista dei cluster; non c’è alcun passaggio di rivendicazione. È il percorso per la CI. Tieni il token in un secret store, mai nello spec.

Note di sicurezza

• Un fingerprint è un’informazione pubblica: identifica una chiave pubblica ma non può impersonarti. La chiave di rivendicazione funziona perché solo il tuo progetto Hetzner può contenere la chiave che kubehz ha generato per il tuo cluster.
• La piattaforma non si connette mai verso l’interno del tuo cluster. I dati sullo stato viaggiano solo in uscita, tramite l’agent heartbeat.
• Se la verifica fallisce, la dashboard lo segnala (“Claim verification failed”) e nulla viene collegato.

Dopo la rivendicazione

• Il cluster esce dallo stato Creating e compare subito nella tua lista dei cluster
• I dettagli sullo stato (nodi, stato dei componenti, scadenza dei certificati) si popolano con l’arrivo degli heartbeat, aggiornati ogni 5 minuti
• Connected significa che un heartbeat è stato ricevuto negli ultimi 15 minuti; dalla cronologia degli heartbeat la dashboard ricava inoltre un uptime a 30 giorni

Risoluzione dei problemi

Sintomo	Soluzione
Fingerprint non accettato	Usa il fingerprint stampato da lo kubehz register, oppure leggilo dalla Hetzner Console (Security → SSH keys, chiave kubehz-claim-<domain>). Riesegui lo kubehz register con HCLOUD_TOKEN impostato per generare una chiave nuova
Codice di rivendicazione “not found”	I codici sono monouso e scadono insieme alla registrazione. Usa la chiave di rivendicazione
La pagina “Tramite agent” continua ad attendere	L’agent non ha battuto da quando hai inserito il nonce. Controlla kubectl -n kubehz-system get cronjob kubehz-heartbeat, poi genera un nuovo nonce
Chiave assente su Hetzner	lo kubehz register non è riuscito a caricare la chiave di rivendicazione. Verifica che HCLOUD_TOKEN abbia permessi Read & Write sul progetto, poi rieseguilo
Cluster non ancora registrato	Esegui prima lo kubehz register. Vedi Registrazione

Prossimi passi

• Dashboard: cosa puoi vedere e fare dopo la rivendicazione
• Registrazione: la metà CLI dell’handshake
• Prezzi: cosa copre il piano gratuito

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-09-05