Il token Hetzner

Collegare 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 accende 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 serviti dal token di piattaforma di kubehz. Poiché il tuo account Hetzner può avere prezzi diversi (ad esempio negoziati), questi sono i prezzi di listino di Hetzner — contrassegnati da un asterisco (*) perché sia chiaro che sono una stima, non la tua fattura.

Puoi creare un cluster hosted. Un cluster con il solo control plane non richiede alcun token — kubehz gestisce il control plane sulla propria infrastruttura. Un token serve solo quando vuoi aggiungere worker sul tuo account.

Con un token

Collega un token nel wizard di creazione o più tardi nella pagina del cluster. Quale token usi decide cosa si sblocca:

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

Un token di sola lettura fornisce comunque i prezzi esatti del tuo account. Si autentica, quindi i prezzi diventano le cifre reali del tuo account — ma il provisioning resta bloccato, e la dashboard lo dice. Per fare provisioning, sostituiscilo con un token Read & Write.

Creare il token

Nella Hetzner Cloud Console scegli il progetto in cui devono vivere i tuoi worker, poi Security → API tokens → Generate API token. Scegli Read & Write se vuoi fare provisioning; Read basta per i soli prezzi.

Come viene validato alla connessione

Quando colleghi o sostituisci un token, kubehz lo verifica prima di conservarlo:

• Deve autenticarsi — un token che Hetzner rifiuta viene respinto subito.
• Deve essere il progetto giusto — per un cluster che ha già server, kubehz conferma che il token appartiene allo stesso progetto Hetzner di quei worker. Un token di un progetto diverso viene rifiutato per non lasciare isolati i tuoi node esistenti. (Un token hcloud appartiene esattamente a un progetto. Dove il controllo non può essere eseguito — nessun server ancora provisionato, o Hetzner irraggiungibile — è indulgente e conserva il token.)

Come viene conservato

Cifrato a riposo, mai restituito. Il token è cifrato prima di toccare il nostro database ed è usato solo per gestire le risorse del tuo cluster. La dashboard non mostra più il valore — solo se un token è collegato e da quando. Puoi sostituirlo in qualsiasi momento; collegare o sostituire un token richiede un 2FA fresco. Revocalo nella Hetzner Cloud Console quando vuoi.

Con la CLI lo

Se guidi il provisioning da lok8s, lo provision con un KUBEHZ_TOKEN (un token API clusters:write creato nella dashboard sotto Access → API Tokens) rivendica il cluster direttamente al tuo tenant. Per consegnare 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, il tuo HCLOUD_TOKEN è usato solo localmente da lo e non viene mai inviato a kubehz — e senza un KUBEHZ_TOKEN non viene inviato nulla a kubehz.

Prossimi passi

• Control plane hosted — i piani 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 sblocca il provisioning
Ultima revisione	2026-07-16