Rivendicazione

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

La registrazione si limita ad annunciare un cluster — viene creato come pending (in attesa), senza proprietario. Chiunque potrebbe annunciare qualsiasi dominio, quindi la proprieta richiede una prova. Ci sono due modi per fornirla: il codice di rivendicazione stampato alla registrazione (il più semplice), oppure la verifica che la chiave SSH con cui e stato eseguito il provisioning del cluster esista nel tuo account Hetzner Cloud.

Opzione 1 — codice di rivendicazione (il più semplice)

La registrazione stampa un codice di rivendicazione monouso. Ne hai uno? Allora rivendicare è un solo incolla:

1. Apri la dashboard su app.kubehz.cloud e accedi
2. Vai alla pagina Rivendica (Claim)
3. Incolla il codice di rivendicazione — 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 token 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 verifica del fingerprint qui sotto oppure registra di nuovo il cluster per ottenere un nuovo codice.

Opzione 2 — fingerprint SSH + token Hetzner

Nessun codice di rivendicazione a portata di mano? Dimostra la proprietà tramite la chiave SSH con cui è stato eseguito il provisioning del cluster: deve esistere nel tuo account Hetzner Cloud.

Cosa ti serve

1. Il fingerprint MD5 stampato da lo provision / lo kubehz register. Puoi ricalcolarlo in qualsiasi momento dalla chiave pubblica configurata nel tuo cluster.lok8s.yaml (spec.hcloud.sshPublicKeyFile):

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

2. Un token API Hetzner Cloud per il progetto che contiene quella chiave SSH. Un token in sola lettura e sufficiente. Crealo nella Hetzner Cloud Console sotto Security → API tokens.

Rivendica il cluster

1. Apri la dashboard su app.kubehz.cloud e accedi
2. Vai alla pagina Rivendica (Claim)
3. Incolla il fingerprint — MD5:aa:bb:cc:… oppure la forma semplice aa:bb:cc:…, entrambe accettate
4. Incolla il tuo token API Hetzner Cloud
5. Clicca Rivendica Cluster

kubehz usa il token una sola volta, lato server, per elencare le chiavi SSH nel tuo progetto Hetzner e verificare che una di esse corrisponda al fingerprint. In caso di successo il cluster viene collegato al tuo tenant e si apre la sua pagina di dettaglio.

Come viene gestito il tuo token Hetzner

• Usato una volta sola — una singola lettura delle tue chiavi SSH al momento della rivendicazione, nient'altro
• Mai memorizzato — scartato subito dopo la verifica; non viene scritto nel database ne registrato nei log
• Privilegio minimo — basta un token in sola lettura; kubehz non crea, modifica o elimina mai nulla nel tuo account Hetzner
• Buona pratica: crea un token dedicato solo alla rivendicazione ed eliminalo poi dalla Hetzner Console

Note di sicurezza

• Il fingerprint e un'informazione pubblica: identifica la tua chiave pubblica ma non puo impersonarti. E esattamente per questo che il percorso del fingerprint richiede in aggiunta la verifica tramite token Hetzner.
• La piattaforma non si connette mai verso l'interno del tuo cluster. I dati sullo stato viaggiano solo in uscita, tramite il CronJob heartbeat.
• Se la verifica fallisce, la dashboard lo segnala ("Claim verification failed") e nulla viene collegato.

Dopo la rivendicazione

• Il cluster esce dallo stato pending 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 e stato ricevuto negli ultimi 15 minuti; dalla cronologia degli heartbeat la dashboard ricava inoltre un uptime a 30 giorni

Risoluzione dei problemi

Sintomo	Soluzione
Codice di rivendicazione "not found"	I codici sono monouso e scadono insieme alla registrazione pending — registra di nuovo il cluster per ottenere un nuovo codice, oppure usa il percorso fingerprint + token
Fingerprint non accettato	Ricalcolalo con ssh-keygen -E md5 — kubehz confronta la forma MD5, perche Hetzner espone fingerprint MD5
La verifica fallisce nonostante il fingerprint corretto	Assicurati che il token appartenga al progetto Hetzner che contiene davvero la chiave SSH
Chiave assente su Hetzner	La chiave pubblica del cluster.lok8s.yaml deve esistere nel tuo progetto Hetzner Cloud (c'e, se lok8s ha eseguito il provisioning del cluster con essa)
Cluster non ancora registrato	Esegui prima lo kubehz register — vedi Registrazione

Prossimi passi

• Dashboard — cosa puoi vedere e fare dopo la rivendicazione
• Registrazione — la meta CLI dell'handshake
• Prezzi — cosa copre il piano gratuito

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-07-10