Chiavi agente

Una chiave agente è un accesso per una macchina: un agente di IA, un job di CI o uno script. La chiave funziona con l’API di kubehz, con kubectl sui tuoi cluster ospitati e sui tuoi spazi, e con il server MCP. È composta da un client ID e da un client secret. Non usa mai la tua password, e ogni chiave scade.

Un’app di IA come Claude o ChatGPT può agire a tuo nome anche senza chiave. Vedi Collega un’app a tuo nome.

Crea una chiave

Ti serve il ruolo Owner o Admin nel tenant. Un tenant può avere al massimo 25 chiavi attive.

1. Nella dashboard, apri Accesso → Chiavi agente.
2. Fai clic su Nuova chiave agente.
3. In Nome, scrivi un nome di al massimo 64 caratteri, per esempio ci-agent.
4. In Ruolo, seleziona Visualizzatore, Editor o Admin.
5. In Portata, seleziona Cluster e spazi scelti o Tutto il tenant.
6. Se hai selezionato Cluster e spazi scelti, spunta i cluster e gli spazi che la chiave può raggiungere.
7. In Scade dopo (giorni), scrivi un numero da 1 a 90. Il valore predefinito è 30.
8. Facoltativo: in Tetto di spesa mensile in euro (facoltativo), scrivi un tetto.
9. Fai clic su Crea chiave.
10. Se si apre una finestra di accesso, conferma con il tuo secondo fattore.
11. Copia il Client secret e il blocco Ambiente per il comando lo kubehz token. kubehz mostra il secret solo questa volta.
12. Fai clic su L’ho salvato.

Ruolo

Ruolo	Nell’API di kubehz	Nei cluster e negli spazi
Visualizzatore	Legge cluster e spazi	Legge, senza secret
Editor	Inoltre crea, modifica ed elimina cluster e spazi	Legge e scrive la maggior parte delle risorse
Admin	Come Editor. Inoltre legge il registro di audit e la fatturazione e può collegare il token di Hetzner Cloud	Controllo completo, anche su secret e RBAC

Portata

• Cluster e spazi scelti è il valore predefinito. La chiave raggiunge solo i cluster e gli spazi che spunti, al massimo 50 per tipo. Raggiunge anche ciò che crea da sé. Se non spunti nulla, la chiave raggiunge solo ciò che crea da sé.
• Tutto il tenant: la chiave raggiunge tutti i cluster e gli spazi del tenant, anche quelli che qualcuno crea in seguito.

Tetto di spesa

Il tetto conta il costo dei cluster e degli spazi che la chiave ha creato, per mese di calendario (UTC). Quando il costo raggiunge il tetto, la chiave non può creare un cluster o uno spazio, estendere una durata o modificare un cluster. Ciò che è già in funzione continua a funzionare e a costare, finché qualcuno lo elimina o la sua durata finisce. Il tetto quindi ferma la nuova spesa. Non è un limite rigido.

• Il conteggio usa il prezzo pieno, senza quota gratuita e senza sconto.
• Il conteggio può essere indietro fino a un’ora.
• Il conteggio riparte il 1° di ogni mese (UTC).
• Il tetto va da 1 a 100.000 euro. Lascia il campo vuoto per nessun tetto.

Usa la chiave con kubectl

La kubeconfig per agenti funziona sui cluster ospitati e sugli spazi. Un cluster self-hosted ha il proprio RBAC. La chiave lo raggiunge solo attraverso l’API di kubehz.

Ti serve lo, la CLI di lok8s, sulla macchina che esegue kubectl.

1. Apri la pagina del cluster ospitato o dello spazio.
2. Fai clic su Scarica kubeconfig per agenti (cluster) o Scarica la kubeconfig per agenti (spazio).
3. Salva il file come agent.kubeconfig.
4. Imposta le quattro variabili del blocco Ambiente per il comando lo kubehz token.
5. Esegui kubectl con il file.

export KUBEHZ_AGENT_CLIENT_ID='...'
export KUBEHZ_AGENT_CLIENT_SECRET='...'
export KUBEHZ_AGENT_TOKEN_URL='https://id.kubehz.cloud/oauth/v2/token'
export KUBEHZ_AGENT_SCOPE='...'
kubectl --kubeconfig agent.kubeconfig get pods

Il file non contiene secret. kubectl esegue lo kubehz token, che ottiene un token con la chiave. lo conserva il token fino a cinque minuti prima della sua scadenza, così una chiamata kubectl non costa un nuovo accesso.

Usa la chiave con l’API

lo kubehz token --format token stampa solo il token:

TOKEN=$(lo kubehz token --format token)
curl -s -H "Authorization: Bearer $TOKEN" https://api.kubehz.cloud/api/agent-keys/self

Senza lo, usa il grant OAuth client credentials:

TOKEN=$(curl -s -u "$KUBEHZ_AGENT_CLIENT_ID:$KUBEHZ_AGENT_CLIENT_SECRET" \
  -d grant_type=client_credentials --data-urlencode "scope=$KUBEHZ_AGENT_SCOPE" \
  "$KUBEHZ_AGENT_TOKEN_URL" | jq -r .access_token)

GET /api/agent-keys/self mostra il ruolo, la portata e la scadenza della chiave, e la sua spesa di questo mese con il tetto. Per una chiave con Cluster e spazi scelti elenca anche i cluster e gli spazi che la chiave raggiunge.

Durata: ciò che un agente crea finisce da solo

Uno spazio o un cluster ospitato che una chiave agente crea ha sempre una durata. La durata è di due ore, o delle ore che la creazione indica (leaseHours, da 1 a 720). Quando la durata finisce, kubehz elimina lo spazio o il cluster. Così un agente che si ferma o dimentica non può lasciare un cluster che gira e costa.

• Per estendere la durata, l’agente invia PATCH /api/spaces/{id}/lease o PATCH /api/clusters/{id}/lease con {"hours": 24}. La nuova fine è tra 24 ore da adesso.
• Estendi la durata prima che finisca. Dopo la fine, kubehz rifiuta ogni modifica, anche un’estensione (LEASE_ENDED). Puoi ancora leggere o eliminare lo spazio o il cluster. kubehz lo elimina entro pochi minuti.
• Una chiave agente non può rimuovere una durata. Una persona con il ruolo Owner o Admin può farlo. Per uno spazio, fai clic su Rimuovi la durata nella sua pagina. Per un cluster ospitato, invia {"hours": null} all’API.
• Una persona che imposta una durata, o ne avvicina la fine, conferma con il secondo fattore. Per estendere o rimuovere una durata non serve il secondo fattore.
• Una durata di più di sei ore riceve un’e-mail circa un’ora prima della fine. L’e-mail va all’owner del tenant. Per fermarla, in Impostazioni → Notifiche disattiva La durata sta per finire.
• Un cluster self-hosted non ha mai una durata. kubehz non chiude ciò che gira sul tuo account Hetzner.

Nella pagina di uno spazio con una durata, la scheda Durata mostra la fine. Per impostare una nuova fine, scrivi le ore in Ore da adesso, poi fai clic su Estendi la durata.

Che cosa una chiave non può fare

• Creare chiavi agente o token API, gestire i membri, o attivare e disattivare le app IA.
• Rimuovere una durata.
• Con il ruolo Visualizzatore: modificare un cluster o uno spazio.
• Con il ruolo Visualizzatore o Editor: leggere il registro di audit o la fatturazione, o collegare il token di Hetzner Cloud.
• Con Cluster e spazi scelti: vedere altri cluster e spazi, o leggere dati dell’intero tenant, per esempio i suoi costi.
• Usare kubectl su un cluster self-hosted.

Revoca una chiave

1. Apri Accesso → Chiavi agente.
2. Nella riga della chiave, fai clic su Revoca.
3. Nella finestra di dialogo, fai clic su Revoca.

L’API di kubehz rifiuta subito la chiave. Anche il server MCP la rifiuta, perché ogni chiamata a uno strumento passa dall’API. Un token che l’agente ha già funziona su cluster e spazi fino alla sua scadenza, al massimo 12 ore. Non puoi annullare una revoca.

Una chiave finisce anche alla sua data di scadenza. L’elenco avvisa 14 giorni prima della fine, e di nuovo 3 giorni prima.