Connessione con kubectl

Una volta che il tuo cluster hosted è in esecuzione, ti ci connetti con un kubeconfig che scarichi dalla dashboard (apri il cluster, poi la scheda Kubeconfig). kubehz ne offre due tipi, e quello predefinito è quello che vuoi.

Hosted

Questa pagina descrive come funziona l’accesso per un cluster hosted; per un cluster self-hosted possiedi già il tuo kubeconfig.

Il kubeconfig OIDC (predefinito)

Il download predefinito è un kubeconfig OIDC. Non contiene alcuna credenziale a lunga durata: invece dice a kubectl di autenticarti tramite kubehz (lo stesso login che usi per la dashboard) e di usare quell’identità. Il tuo accesso al cluster segue la tua appartenenza al team e il tuo ruolo: ciò che kubectl può fare è esattamente ciò che il tuo ruolo consente.

Questo è il modo consigliato per connettersi: nel file non risiede nulla di segreto, l’accesso segue il tuo login attivo e, se lasci il team, il tuo accesso termina con esso.

Configurazione una tantum: installa kubelogin

Il kubeconfig OIDC usa il plugin kubelogin (kubectl oidc-login) per gestire l’accesso via browser. Installalo una volta:

# krew (any platform)
kubectl krew install oidc-login

# or Homebrew (macOS / Linux)
brew install int128/kubelogin/kubelogin

Connessione

1. Nella dashboard, apri il tuo cluster e la scheda Kubeconfig.

2. Scarica il kubeconfig OIDC (quello predefinito) e salvalo, ad esempio in ~/.kube/kubehz-<cluster>.yaml.

3. Punta kubectl su di esso ed esegui un comando qualsiasi:

   export KUBECONFIG="$HOME/.kube/kubehz-<cluster>.yaml"
   kubectl get nodes
   
   # Con un pool di worker:
   # NAME       STATUS   ROLES    AGE   VERSION
   # worker-1   Ready    <none>   4m    v1.31.4
   
   # Cluster con solo control plane, nessun pool — questo è un SUCCESSO:
   # No resources found

   Un elenco vuoto non è una connessione fallita. Un control plane hosted non ha nodi propri: No resources found significa che kubectl ha raggiunto il tuo API server e che questo ha risposto. Aggiungi capacità in Worker Pools.

   Il primo comando apre il browser per accedere a kubehz. Dopodiché il token viene messo in cache e kubectl funziona normalmente finché non scade, momento in cui ti chiede semplicemente di accedere di nuovo.

Se un comando restituisce Forbidden, il tuo ruolo non concede quell’azione; vedi Accesso e ruoli.

Il kubeconfig admin (avanzato, sconsigliato)

È disponibile anche un kubeconfig admin sotto un’opzione Avanzata, ma lo sconsigliamo:

• incorpora un certificato client a lunga durata, non legato alla tua identità;
• non può essere revocato se non ruotando la CA del cluster;
• concede sempre pieno cluster-admin, ignorando il tuo ruolo.

Usalo solo come ripiego break-glass (ad esempio, se il percorso OIDC non è disponibile). Poiché è sensibile, è protetto da due gate:

1. Abilitalo prima nelle Impostazioni del cluster: questo richiede un accesso a due fattori fresco e una casella di consenso esplicito. Finché non lo fai, il download admin non è disponibile.
2. Scarica: il download stesso richiede un ulteriore accesso a due fattori fresco.

Ogni abilitazione, disabilitazione e download è registrato nel log di audit del tuo account. Disattiva di nuovo l’opzione nelle Impostazioni quando non ne hai più bisogno.

Prossimi passi

• Accesso e ruoli: cosa può fare ogni membro, e i ruoli personalizzati limitati ai namespace.
• Identità e accesso: come il tuo login si mappa all’accesso al cluster.
• Add-on: il visualizzatore di cluster integrato nella dashboard e gli altri add-on hosted.

---

Stato del documento

Aspetto	Dettaglio
Stato	live: il kubeconfig OIDC è il default; quello admin è protetto due volte
Ultima revisione	2026-07-14