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 utilizzi 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 quando si utilizzano i 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, puoi 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 Kubernetes Engine da una VM Compute Engine che non ha l'ambito cloud-platform.

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

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

Quando si tenta 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 provider di autenticazione trovato

Il seguente errore si verifica se i client kubectl o Kubernetes personalizzati sono stati compilati con Kubernetes client-go versione 1.26 o successive:

no Auth Provider found for name "gcp"

Per risolvere il problema, svolgi i seguenti passaggi:

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

  2. Esegui l'aggiornamento alla versione più recente dellgcloud CLI:

    gcloud components update

  3. Aggiorna il file kubeconfig:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • COMPUTE_REGION: la regione Compute Engine per il cluster. Per i cluster di zona, utilizza --zone=COMPUTE_ZONE.

Errore: il plug-in di autenticazione gcp è deprecato. Utilizza gcloud

Dopo aver installato gke-gcloud-auth-plugin e aver eseguito un comando kubectl su un cluster GKE, potresti visualizzare il seguente messaggio di avviso:

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 cliente di utilizzare il gke-gcloud-auth-plugin plug-in di autenticazione:

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

    Bash

    vi ~/.bashrc

    Zsh

    vi ~/.zshrc

    Se utilizzi PowerShell, salta 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.

  4. Aggiorna gcloud CLI:

    gcloud components update

  5. Esegui l'autenticazione sul cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • COMPUTE_REGION: la regione Compute Engine per il cluster. Per i cluster di zona, utilizza --zone=COMPUTE_ZONE.

Problema: il comando kubectl non viene trovato

Se ricevi un messaggio che indica che il comando kubectl non è stato trovato, reinstalla il file 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 ti consente di utilizzare i comandi kubectl senza digitare il percorso completo.

    In alternativa, aggiungi la seguente riga alla posizione in cui 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 seguente comando per caricare il file aggiornato. Nell'esempio riportato di seguito 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

Sostituisci CLUSTER_NAME con il nome del cluster. Se non sai cosa inserire come nome del cluster, utilizza il seguente comando per elencare i cluster:

gcloud container clusters list

Errore: il comando kubectl ha superato il tempo di attesa

Se hai creato un cluster e hai tentato di eseguire un comando kubectl sul cluster, ma il comando kubectl ha superato il tempo di attesa, 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 piano di controllo.

  2. Imposta le credenziali del cluster:

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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • COMPUTE_LOCATION: la posizione di Compute Engine.
    • 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 del computer da cui stai tentando di effettuare la connessione. Puoi trovare le reti autorizzate esistenti nella console o eseguendo il seguente comando:

    gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_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 nell'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 tuo cluster ha nodi. Se hai ridotto a zero il numero di nodi nel cluster, 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 i tunnel SSH o Konnectivity Proxy per abilitare la comunicazione sicura. Le sezioni seguenti descrivono i passaggi per la risoluzione dei problemi specifici di ciascun servizio:

Risolvere i problemi relativi a SSH

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

Le seguenti impostazioni possono causare problemi di comunicazione SSH:

  • Le regole firewall della rete non consentono l'accesso SSH dal piano di controllo.

    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 (è necessaria una chiave privata valida). GKE inserisce anche una regola SSH per ogni cluster pubblico del tipo gke-CLUSTER_NAME-RANDOM_CHARACTERS-ssh che consente l'accesso SSH specificamente dal piano di controllo del cluster ai nodi del cluster.

    Se nessuna di queste regole esiste, il piano di controllo non può aprire i tunnel SSH.

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

    Per risolvere il problema, identifica il tag presente su 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 piano di controllo.

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

    Se la voce dei metadati del progetto denominata ssh-keys è vicina al suo limite di dimensione massimo, GKE non è in grado di aggiungere la propria chiave SSH per l'apertura dei tunnel SSH.

    Per verificare che il problema sia questo, controlla la lunghezza dell'elenco di ssh-keys. Puoi visualizzare i metadati del tuo progetto eseguendo il seguente comando, eventualmente includendo 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 piano di controllo nei metadati del progetto non verrà rispettata dai nodi.

    Per verificare che si tratti del 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 relativi al 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 dispongano dell'accesso al 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 in uscita al control plane del cluster sulla porta 8132 (per fare un confronto, il server API utilizza la porta 443). Se hai regole che negano l'accesso in uscita, potresti dover modificare le regole 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 del firewall consentano i seguenti tipi di traffico:

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

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

Modificare il criterio di rete

Se il criterio di rete del tuo cluster blocca l'ingresso dallo spazio dei nomi kube-system allo spazio dei nomi workload, possono verificarsi problemi con il proxy Konnectivity.

Queste funzionalità non sono necessarie per il corretto funzionamento del cluster. Se preferisci mantenere la rete del cluster bloccata per tutto l'accesso esterno, tieni presente che funzionalità come queste non funzioneranno.

Per verificare che questa sia la causa del problema, trova i criteri di rete nello spazio dei nomi interessato eseguendo il seguente comando:

kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

Per risolvere il problema, aggiungi quanto segue al campo spec.ingress delle norme di rete:

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

Passaggi successivi

Se hai bisogno di ulteriore assistenza, contatta l'assistenza clienti Google Cloud.