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 informazioni correlate, consulta le seguenti risorse:

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 dei service account per le istanze nella documentazione di Compute Engine.

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

Quando tenti 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 file 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 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"

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, visualizzerai 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 restituiscono un errore durante la negoziazione di 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 (richiedendo 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, poi 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 progetto per ssh-keys è piena.

    Se la voce dei 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 questo sia 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 nel 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 dispongano dell'accesso firewall richiesto e che i criteri di rete siano configurati correttamente.

Consenti l'accesso al firewall richiesto

Verifica che le regole 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 di 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 questo 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 alla policy di uscita, aggiungi quanto segue al campo spec.egress delle policy 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 per il 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.

Errore: i comandi kubectl non vanno a buon fine e viene visualizzato l'errore Nessun agente disponibile

Quando esegui comandi kubectl che devono connettersi dal control plane GKE a un pod, ad esempio kubectl exec, kubectl logs o kubectl port-forward, il comando potrebbe non riuscire e restituire messaggi di errore simili ai seguenti:

Error from server: error dialing backend: No agent available

failed to call webhook: Post "https://WEBHOOK_SERVICE.WEBHOOK_NAMESPACE.svc:PORT/PATH?timeout=10s": No agent available

v1beta1.metrics.k8s.io failed with: failing or missing response from https://NODE_IP:10250/apis/metrics.k8s.io/v1beta1: Get "https://NODE_IP:10250/apis/metrics.k8s.io/v1beta1": No agent available

Questi errori indicano un problema con Konnectivity, il tunnel di comunicazione sicuro tra il piano di controllo GKE e i nodi del cluster. In particolare, significa che konnectivity-server sul control plane non può connettersi a nessun pod konnectivity-agent integro nello spazio dei nomi kube-system.

Per risolvere il problema, prova le seguenti soluzioni:

  1. Verifica l'integrità dei pod konnectivity-agent:

    1. Controlla se i pod konnectivity-agent sono in esecuzione:

      kubectl get pods -n kube-system -l k8s-app=konnectivity-agent

      L'output è simile al seguente:

      NAME                                   READY   STATUS    RESTARTS  AGE
konnectivity-agent-abc123def4-xsy1a    2/2     Running   0         31d
konnectivity-agent-abc123def4-yza2b    2/2     Running   0         31d
konnectivity-agent-abc123def4-zxb3c    2/2     Running   0         31d

      Controlla il valore nella colonna Status. Se i pod hanno lo stato Running, esamina i log per verificare la presenza di problemi di connessione. In caso contrario, indaga sul motivo per cui i pod non sono in esecuzione.

    2. Esamina i log per verificare la presenza di problemi di connessione. Se i pod hanno lo stato Running, controlla i log per problemi di connessione. Poiché il comando kubectl logs dipende da Konnectivity, utilizza Esplora log nella consoleGoogle Cloud :

      1. Nella console Google Cloud , vai a Esplora log.

        Vai a Esplora log

      2. Nel riquadro della query, inserisci la seguente query.

        resource.type="k8s_container"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.namespace_name="kube-system"
labels."k8s-pod/k8s-app"="konnectivity-agent"
resource.labels.container_name="konnectivity-agent"

        Sostituisci CLUSTER_NAME con il nome del tuo cluster.

      3. Fai clic su Esegui query.

      4. Rivedi l'output. Quando esamini i log di konnectivity-agent, cerca gli errori che indicano il motivo per cui l'agente non riesce a connettersi. Gli errori di autenticazione o autorizzazione spesso indicano un webhook configurato in modo errato che blocca le revisioni dei token. Gli errori "Connessione rifiutata" o "Timeout" in genere indicano che una regola firewall o un criterio di rete blocca il traffico verso il control plane sulla porta TCP 8132 oppure blocca il traffico tra l'agente Konnectivity e altri nodi. Gli errori di certificato suggeriscono che un firewall o un proxy sta ispezionando e interferendo con il traffico TLS criptato.

    3. Scopri perché i pod non sono in esecuzione. Se i pod hanno lo stato Pending o un altro stato non in esecuzione, indaga sulla causa. konnectivity-agent viene eseguito come Deployment, non come DaemonSet. Poiché viene eseguito come Deployment, i pod dell'agente devono essere eseguiti solo su un sottoinsieme di nodi. Tuttavia, se questo sottoinsieme specifico di nodi non è disponibile, l'intero servizio può non funzionare.

      Le cause comuni di un pod non in esecuzione includono:

      • Incompatibilità dei nodi personalizzate che impediscono la pianificazione di un pod.
      • Risorse del nodo insufficienti (CPU o memoria).
      • Policy di autorizzazione binaria restrittive che bloccano le immagini di sistema GKE.

      Per ottenere maggiori dettagli sul motivo per cui un pod specifico non è in esecuzione, utilizza il comando kubectl describe:

      kubectl describe pod POD_NAME -n kube-system

      Sostituisci POD_NAME con il nome del pod che non è in esecuzione.

  2. Esamina i webhook di ammissione per assicurarti che nessuno blocchi le richieste API TokenReview. konnectivity-agent si basa sui token del service account, pertanto l'interferenza con le revisioni dei token può impedire agli agenti di connettersi. Se la causa è un webhook, Konnectivity non può eseguire il ripristino finché il webhook difettoso non viene rimosso o riparato.

  3. Assicurati che le regole firewall consentano il traffico TCP in uscita dai nodi GKE all'indirizzo IP del control plane sulla porta 8132. Questa connessione è necessaria per consentire a konnectivity-agent di raggiungere il servizio Konnectivity. Per ulteriori informazioni, vedi Consentire l'accesso al firewall richiesto.

  4. Assicurati che non esistano regole di policy di rete che limitano il traffico essenziale di Konnectivity. Le regole dei criteri di rete devono consentire sia il traffico intra-cluster (da pod a pod) all'interno dello spazio dei nomi kube-system sia il traffico in uscita dai pod konnectivity-agent al piano di controllo GKE.

Passaggi successivi