Risolvere i problemi relativi allo strumento a riga di comando kubectl

Questa pagina mostra come risolvere i problemi relativi allo strumento a riga di comando kubectl quando lavori in Google Kubernetes Engine (GKE). Per consigli più generali, consulta la sezione Risoluzione dei problemi di kubectl nella documentazione di Kubernetes.

Errori di autenticazione e autorizzazione

Se si verificano errori relativi all'autenticazione e all'autorizzazione durante l'utilizzo dei comandi dello strumento a riga di comando kubectl, leggi le sezioni seguenti per ricevere consigli.

Errore: 401 (non autorizzato)

Quando ti connetti ai cluster GKE, potresti ricevere un errore di autenticazione e autorizzazione con il codice di stato HTTP 401 (Unauthorized). Questo problema potrebbe verificarsi quando provi a eseguire un comando kubectl nel tuo cluster GKE da un ambiente locale. Per saperne di più, consulta Problema: errori di autenticazione e autorizzazione.

Errore: ambiti di autenticazione insufficienti

Quando esegui gcloud container clusters get-credentials, potresti ricevere il seguente errore:

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.

Questo errore si verifica perché stai tentando di accedere all'API GKE da una VM Compute Engine che non dispone dell'ambito cloud-platform.

Per risolvere questo errore, concedi l'ambito cloud-platform mancante. Per istruzioni su come modificare gli ambiti nell'istanza VM di Compute Engine, consulta Creazione e attivazione di service account per le istanze nella documentazione di Compute Engine.

Errore: eseguibile gke-gcloud-auth-plugin non trovato

Durante il tentativo di eseguire comandi kubectl o client personalizzati che interagiscono con GKE, possono verificarsi messaggi di errore simili ai seguenti:

Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found

It looks like you are trying to use a client-go credential plugin that is not installed.

To learn more about this feature, consult the documentation available at:
      https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins

Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.

Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory

Per risolvere il problema, installa gke-gcloud-auth-plugin come descritto in Installare i plug-in richiesti.

Errore: nessun fornitore di autenticazione trovato

Si verifica il seguente errore se kubectl o i client Kubernetes personalizzati sono stati creati con Kubernetes client-go versione 1.26 o successive:

no Auth Provider found for name "gcp"

Per risolvere il problema, completa i seguenti passaggi:

  1. Installa gke-gcloud-auth-plugin come descritto in Installare i plug-in richiesti.

  2. Esegui l'aggiornamento all'ultima versione di gcloud CLI:

    gcloud components update

  3. Aggiorna il file kubeconfig:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • CONTROL_PLANE_LOCATION: la posizione di Compute Engine del control plane del tuo cluster. Fornisci una regione per i cluster regionali o una zona per i cluster zonali.

Errore: il plug-in gcp auth è deprecato, utilizza gcloud

Potresti visualizzare il seguente messaggio di avviso dopo aver installato gke-gcloud-auth-plugin ed eseguito un comando kubectl su un cluster GKE:

WARNING: the gcp auth plugin is deprecated in v1.22+, unavailable in v1.25+; use gcloud instead.

Questo messaggio viene visualizzato se la versione del client è precedente alla 1.26.

Per risolvere il problema, chiedi al tuo cliente di utilizzare il plug-in di autenticazione gke-gcloud-auth-plugin:

  1. Apri lo script di accesso alla shell in un editor di testo:

    Bash

    vi ~/.bashrc

    Zsh

    vi ~/.zshrc

    Se utilizzi PowerShell, ignora questo passaggio.

  2. Imposta la seguente variabile di ambiente:

    Bash

    export USE_GKE_GCLOUD_AUTH_PLUGIN=True

    Zsh

    export USE_GKE_GCLOUD_AUTH_PLUGIN=True

    PowerShell

    [Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')

  3. Applica la variabile nel tuo ambiente:

    Bash

    source ~/.bashrc

    Zsh

    source ~/.zshrc

    PowerShell

    Esci dal terminale e apri una nuova sessione del terminale.

  4. Aggiorna gcloud CLI:

    gcloud components update

  5. Esegui l'autenticazione sul cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • CONTROL_PLANE_LOCATION: la posizione di Compute Engine del control plane del tuo cluster. Fornisci una regione per i cluster regionali o una zona per i cluster zonali.

Problema: il comando kubectl non viene trovato

Se ricevi un messaggio che indica che il comando kubectl non è stato trovato, reinstalla il binario kubectl e imposta la variabile di ambiente $PATH:

  1. Installa il programma binario kubectl:

    gcloud components update kubectl

  2. Quando il programma di installazione ti chiede di modificare la variabile di ambiente $PATH, inserisci y per continuare. La modifica di questa variabile consente di utilizzare i comandi kubectl senza digitare il percorso completo.

    In alternativa, aggiungi la seguente riga a dove la shell memorizza le variabili di ambiente, ad esempio ~/.bashrc (o ~/.bash_profile in macOS):

    export PATH=$PATH:/usr/local/share/google/google-cloud-sdk/bin/

  3. Esegui il comando seguente per caricare il file aggiornato. Nell'esempio riportato sotto viene utilizzato .bashrc:

    source ~/.bashrc

    Se utilizzi macOS, usa ~/.bash_profile anziché .bashrc.

Problema: i comandi kubectl restituiscono l'errore "connection refused" (connessione rifiutata)

Se i comandi kubectl restituiscono un errore "connection refused", devi impostare il contesto del cluster con il seguente comando:

gcloud container clusters get-credentials CLUSTER_NAME \
       --location=CONTROL_PLANE_LOCATION

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del tuo cluster.
  • CONTROL_PLANE_LOCATION: la posizione di Compute Engine del control plane del cluster. Fornisci una regione per i cluster regionali o una zona per i cluster zonali.

Se non sai cosa inserire per il nome o la posizione del cluster, utilizza il seguente comando per elencare i cluster:

gcloud container clusters list

Errore: timeout del comando kubectl

Se hai creato un cluster e hai tentato di eseguire un comando kubectl sul cluster, ma il comando kubectl va in timeout, viene visualizzato un errore simile al seguente:

  • Unable to connect to the server: dial tcp IP_ADDRESS: connect: connection timed out
  • Unable to connect to the server: dial tcp IP_ADDRESS: i/o timeout.

Questi errori indicano che kubectl non è in grado di comunicare con il control plane del cluster.

Per risolvere il problema, verifica e imposta il contesto in cui è impostato il cluster e assicurati la connettività al cluster:

  1. Vai a $HOME/.kube/config o esegui il comando kubectl config view per verificare che il file di configurazione contenga il contesto del cluster e l'indirizzo IP esterno del control plane.

  2. Imposta le credenziali del cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --project=PROJECT_ID

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • CONTROL_PLANE_LOCATION: la posizione di Compute Engine del control plane del tuo cluster. Fornisci una regione per i cluster regionali o una zona per i cluster zonali.
    • PROJECT_ID: l'ID del progetto in cui è stato creato il cluster.

  3. Se hai attivato le reti autorizzate nel cluster, assicurati che l'elenco delle reti autorizzate esistenti includa l'IP in uscita della macchina da cui stai tentando di connetterti. Puoi trovare le reti autorizzate esistenti nella console o eseguendo questo comando:

    gcloud container clusters describe CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --project=PROJECT_ID \
    --format "flattened(controlPlaneEndpointsConfig.ipEndpointsConfig.authorizedNetwork
sConfig.cidrBlocks[])"

    Se l'IP in uscita della macchina non è incluso nell'elenco delle reti autorizzate dell'output del comando precedente, completa uno dei seguenti passaggi:

Errore: i comandi kubectl non sono riusciti a negoziare una versione dell'API

Se i comandi kubectl restituiscono un errore failed to negotiate an API version, devi assicurarti che kubectl disponga delle credenziali di autenticazione:

gcloud auth application-default login

Problema: il comando kubectl logs, attach, exec o port-forward smette di rispondere

Se i comandi kubectl logs, attach, exec o port-forward smettono di rispondere, in genere il server API non è in grado di comunicare con i nodi.

Innanzitutto, controlla se il cluster ha nodi. Se hai ridotto il numero di nodi nel cluster a zero, i comandi non funzioneranno. Per risolvere questo problema, ridimensiona il cluster in modo che abbia almeno un nodo.

Se il cluster ha almeno un nodo, controlla se utilizzi SSH o tunnel proxy Konnectivity per abilitare la comunicazione sicura. Le sezioni seguenti descrivono i passaggi per la risoluzione dei problemi specifici per ogni servizio:

Risolvere i problemi relativi a SSH

Se utilizzi SSH, GKE salva un file di chiave pubblica SSH nei metadati del progetto Compute Engine. Tutte le VM Compute Engine che utilizzano immagini fornite da Google controllano regolarmente i metadati comuni del progetto e i metadati dell'istanza per le chiavi SSH da aggiungere all'elenco degli utenti autorizzati della VM. GKE aggiunge anche una regola firewall alla tua rete Compute Engine per consentire l'accesso SSH dall'indirizzo IP del control plane a ogni nodo del cluster.

Le seguenti impostazioni possono causare problemi con la comunicazione SSH:

  • Le regole firewall della tua rete non consentono l'accesso SSH dal control plane.

    Tutte le reti Compute Engine vengono create con una regola firewall denominata default-allow-ssh che consente l'accesso SSH da tutti gli indirizzi IP (richiede una chiave privata valida). GKE inserisce anche una regola SSH per ogni cluster pubblico nel formato gke-CLUSTER_NAME-RANDOM_CHARACTERS-ssh che consente l'accesso SSH specificamente dal control plane del cluster ai nodi del cluster.

    Se non esiste nessuna di queste regole, il control plane non può aprire tunnel SSH.

    Per verificare che questa sia la causa del problema, controlla se la tua configurazione include queste regole.

    Per risolvere il problema, identifica il tag presente in tutti i nodi del cluster, quindi aggiungi di nuovo una regola firewall che consenta l'accesso alle VM con quel tag dall'indirizzo IP del control plane.

  • La voce dei metadati comuni del tuo progetto per ssh-keys è piena.

    Se la voce di metadati del progetto denominata ssh-keys si avvicina al limite di dimensioni massime, GKE non è in grado di aggiungere la propria chiave SSH per aprire tunnel SSH.

    Per verificare che sia questo il problema, controlla la lunghezza dell'elenco di ssh-keys. Per visualizzare i metadati del progetto, esegui il seguente comando, includendo facoltativamente il flag --project:

    gcloud compute project-info describe [--project=PROJECT_ID]

    Per risolvere il problema, elimina alcune delle chiavi SSH che non sono più necessarie.

  • Hai impostato un campo dei metadati con la chiave ssh-keys sulle VM del cluster.

    L'agente del nodo sulle VM preferisce le chiavi SSH per istanza alle chiavi SSH a livello di progetto, quindi se hai impostato chiavi SSH specificamente sui nodi del cluster, la chiave SSH del control plane nei metadati del progetto non verrà rispettata dai nodi.

    Per verificare che si tratti di questo problema, esegui gcloud compute instances describe VM_NAME e cerca un campo ssh-keys nei metadati.

    Per risolvere il problema, elimina le chiavi SSH per istanza dai metadati dell'istanza.

Risolvere i problemi del proxy Konnectivity

Puoi determinare se il tuo cluster utilizza il proxy Konnectivity controllando il seguente deployment di sistema:

kubectl get deployments konnectivity-agent --namespace kube-system

Se il cluster utilizza il proxy Konnectivity, l'output è simile al seguente:

NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
konnectivity-agent   3/3     3            3           18d

Dopo aver verificato di utilizzare il proxy Konnectivity, assicurati che gli agenti Konnectivity abbiano l'accesso firewall richiesto e che i criteri di rete siano configurati correttamente.

Consenti l'accesso al firewall richiesto

Verifica che le regole del firewall della tua rete consentano l'accesso alle seguenti porte:

  • Porta del control plane: durante la creazione del cluster, gli agenti Konnectivity stabiliscono connessioni al control plane sulla porta 8132. Quando esegui un comando kubectl, il server API utilizza questa connessione per comunicare con il cluster. Assicurati di consentire il traffico di uscita al control plane del cluster sulla porta 8132 (per confronto, il server API utilizza la porta 443). Se hai regole che negano l'accesso in uscita, potresti doverle modificare o creare eccezioni.

  • Porta kubelet: poiché gli agenti Konnectivity sono pod di sistema di cui è stato eseguito il deployment sui nodi del cluster, assicurati che le regole firewall consentano i seguenti tipi di traffico:

    • Traffico in entrata verso i tuoi carichi di lavoro sulla porta 10250 dai tuoi intervalli di pod.
    • Traffico in uscita dagli intervalli dei pod.

    Se le regole firewall non consentono questo tipo di traffico, modifica le regole.

Modifica del criterio di rete

Il proxy Konnectivity potrebbe presentare problemi se i criteri di rete del cluster eseguono una delle seguenti operazioni:

  • Blocca l'ingresso dallo spazio dei nomi kube-system allo spazio dei nomi workload
  • Blocca l'uscita verso il control plane del cluster sulla porta 8132

Quando l'ingresso è bloccato dal criterio di rete dei pod del workload, i log konnectivity-agent includono un messaggio di errore simile al seguente:

"error dialing backend" error="dial tcp POD_IP_ADDRESS:PORT: i/o timeout"

Nel messaggio di errore, POD_IP_ADDRESS è l'indirizzo IP del pod del workload.

Quando il traffico in uscita è bloccato dal criterio di rete, i log konnectivity-agent includono un messaggio di errore simile al seguente:

"cannot connect once" err="rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial tcp CP_IP_ADDRESS:8132: i/o timeout

Nell'errore, CP_IP_ADDRESS è l'indirizzo IP del control plane del cluster.

Queste funzionalità non sono necessarie per il corretto funzionamento del cluster. Se preferisci che la rete del cluster sia protetta da qualsiasi accesso esterno, tieni presente che funzionalità come queste non funzioneranno.

Per verificare che le regole di ingresso o di uscita dei criteri di rete siano la causa del problema, individua i criteri di rete nello spazio dei nomi interessato eseguendo il seguente comando:

kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

Per risolvere il problema relativo al criterio di ingresso, aggiungi quanto segue al campo spec.ingress dei criteri di rete:

ingress:
- from:
  - namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: kube-system
    podSelector:
      matchLabels:
        k8s-app: konnectivity-agent

Per risolvere il problema relativo al criterio di uscita, aggiungi quanto segue al campo spec.egress dei criteri di rete:

egress:
- to:
  - ipBlock:
      cidr: CP_IP_ADDRESS/32
  ports:
  - protocol: TCP
    port: 8132

Se la tua policy di rete utilizza una combinazione di regole in entrata e in uscita, valuta la possibilità di modificarle entrambe.

Regolare l'agente di mascheramento IP

Il control plane del cluster accetta il traffico dagli agenti Konnectivity se l'indirizzo IP di origine si trova negli intervalli di indirizzi IP dei pod. Se modifichi la configurazione di ip-masq-agent per mascherare l'indirizzo IP di origine del traffico verso il control plane del cluster, gli agenti Konnectivity potrebbero riscontrare errori di connettività.

Per risolvere il problema e contribuire a garantire che il traffico dagli agenti Konnectivity al control plane del cluster non venga mascherato con l'indirizzo IP del nodo, aggiungi l'indirizzo IP del control plane all'elenco nonMasqueradeCIDRs in ConfigMap ip-masq-agent:

nonMasqueradeCIDRs:
- CONTROL_PLANE_IP_ADDRESS/32

Per ulteriori informazioni su questa configurazione, consulta Agente di mascheramento IP.

Passaggi successivi