Il token Hetzner

Un token API di Hetzner Cloud è opzionale. Non ti serve mai per accedere, sfogliare la dashboard, vedere i prezzi di listino o gestire un cluster hosted con il solo control plane. Un token attiva due cose: i prezzi esatti del tuo account e il provisioning (pool di worker e chiavi SSH sul tuo account Hetzner).

Senza token

Vedi comunque tutto, a prezzi di listino. La dashboard mostra location, tipi di macchina e prezzi di Hetzner. kubehz li legge con il proprio token di piattaforma. Il tuo account Hetzner può avere prezzi diversi (ad esempio prezzi negoziati). Per questo la dashboard mostra i prezzi di listino di Hetzner e li segna con un asterisco (*): sono una stima, non la tua fattura.

Puoi creare un cluster hosted. Un cluster hosted con il solo control plane non richiede alcun token, perché kubehz gestisce il control plane sulla propria infrastruttura. Il token permette a quel cluster di avere worker sul tuo account, e questa scelta la fai una volta sola, alla creazione.

Un cluster creato senza un token collegato non può ottenere worker pool in seguito. Per avere worker, colleghi un token e ricrei il cluster (vedi Worker pool). Se pensi di volere dei worker sul cluster, collega un token prima di crearlo.

Con un token

Collega un token nel wizard di creazione. Puoi aggiungere un token all’account anche più tardi, perché è una credenziale del tenant, non del singolo cluster. Ma i worker pool li scegli alla creazione del cluster: un cluster senza token collegato non può ottenere worker pool in seguito, a meno che tu non lo ricrei (vedi Worker pool). Un token che colleghi dopo dà comunque prezzi esatti per il tuo account. Il tipo di token decide cosa attiva:

Un token Read & Write attiva il provisioning. La dashboard passa dai prezzi di listino ai prezzi esatti del tuo account. Puoi creare e scalare pool di worker: kubehz crea i server sul tuo account, e paghi direttamente Hetzner, senza ricarico kubehz. Puoi anche gestire le chiavi SSH per i worker node.

Un token di sola lettura dà comunque i prezzi esatti del tuo account. Il token si autentica, quindi i prezzi diventano le cifre reali del tuo account. Ma il provisioning resta bloccato, e la dashboard te lo dice. Per fare provisioning, sostituisci il token con un token Read & Write.

Creare il token

Nella Hetzner Cloud Console scegli il progetto per i tuoi worker. Poi seleziona Security → API tokens → Generate API token. Scegli Read & Write se vuoi fare provisioning. Read basta per i soli prezzi.

Come kubehz controlla il token

Quando colleghi o sostituisci un token, kubehz controlla il token prima di conservarlo:

• Il token deve autenticarsi. kubehz respinge un token che Hetzner rifiuta.
• Il token deve appartenere al progetto giusto. Per un cluster che ha già server, kubehz conferma che il token appartiene allo stesso progetto Hetzner di quei worker. kubehz respinge un token di un progetto diverso, così il token non lascia isolati i tuoi node esistenti. (Un token hcloud appartiene esattamente a un progetto.) A volte il controllo non può girare: non c’è ancora nessun server provisionato, oppure Hetzner è irraggiungibile. Allora il controllo è indulgente e kubehz conserva il token.

Come kubehz conserva il token

Cifrato a riposo, mai più mostrato. kubehz cifra il token prima che il token raggiunga il nostro database. kubehz usa il token solo per gestire le risorse del tuo cluster. La dashboard non mostra più il valore. Mostra solo se un token è collegato, e da quando.

Puoi sostituire il token in qualsiasi momento. Per collegare o sostituire un token ti serve una conferma 2FA fresca. Puoi revocare il token nella Hetzner Cloud Console quando vuoi.

Con la CLI lo

Se fai provisioning con lok8s, lo provision con un KUBEHZ_TOKEN rivendica il cluster direttamente al tuo tenant. Un KUBEHZ_TOKEN è un token API clusters:write che crei nella dashboard sotto Accesso → Token API. Per dare a kubehz anche il tuo HCLOUD_TOKEN per il provisioning dalla dashboard, abilitalo esplicitamente:

# cluster.lok8s.yaml
spec:
  kubehz:
    hosting: hosted
    connectHcloudToken: true   # invia HCLOUD_TOKEN a kubehz per il provisioning

È opt-in. Senza connectHcloudToken: true, lo usa il tuo HCLOUD_TOKEN solo localmente e non lo invia mai a kubehz. Senza un KUBEHZ_TOKEN, lo non invia nulla a kubehz.

Prossimi passi

• Control plane hosted: la forma, il prezzo e il percorso hosted in generale.
• Pool di worker: pool, scaling e autoscaling (richiede un token Read & Write).
• Come funziona: il confine di fiducia che il token delega.

---

Stato del documento

Aspetto	Dettaglio
Stato	live: token opzionale, Read & Write attiva il provisioning
Ultima revisione	2026-10-30