Risolvere i problemi dello strumento a riga di comando kubectl

Quando utilizzi Google Kubernetes Engine (GKE), i problemi con lo strumento a riga di comando kubectl possono impedirti di eseguire il deployment delle applicazioni o di gestire le risorse del cluster. In genere, questi problemi rientrano in due categorie: errori di autenticazione, in cui il cluster non riconosce la tua identità, ed errori di connettività, in cui lo strumento non riesce a raggiungere il control plane del cluster.

Utilizza questa pagina per diagnosticare e risolvere questi problemi. Scopri i passaggi per la risoluzione dei problemi di autenticazione e di debug della connettività tra lo strumento kubectl e il control plane del cluster. Scopri come verificare che i plug-in necessari siano installati e configurati e rivedi le considerazioni sulle policy di rete e sul firewall per servizi come SSH e Konnectivity.

Queste informazioni sono importanti per chiunque utilizzi i comandi kubectl per gestire le applicazioni o le risorse del cluster su GKE. È particolarmente importante per gli sviluppatori di applicazioni e gli amministratori e gli operatori della piattaforma che si affidano ai comandi kubectl per le loro attività quotidiane principali. Per saperne di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti di Cloud de Confiance by S3NS, consulta Ruoli e attività comuni degli utenti GKE.

Per informazioni correlate, consulta le seguenti risorse:

Errori di autenticazione e autorizzazione

Se si verificano errori relativi all'autenticazione e all'autorizzazione quando utilizzi i comandi dello strumento a riga di comando kubectl, leggi le sezioni seguenti per suggerimenti.

Errore: 401 (Non autorizzato)

Quando ti connetti ai cluster GKE, potresti ricevere un errore di autenticazione e autorizzazione con codice di stato HTTP 401 (Unauthorized). Questo problema potrebbe verificarsi quando provi a eseguire un comando kubectl nel 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 di Compute Engine che non ha l'ambito cloud-platform.

Per risolvere questo errore, concedi l'ambito cloud-platform mancante. Per istruzioni sulla modifica degli 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

Durante il tentativo di eseguire i comandi kubectl o i 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 Installa i plug-in richiesti.

Errore: nessun provider di autenticazione trovato

Il seguente errore si verifica 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 questo problema, completa i seguenti passaggi:

  1. Installa gke-gcloud-auth-plugin come descritto in Installa 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 località di Compute Engine del control plane del tuo cluster. Specifica una regione per i cluster a livello di regione o una zona per i cluster a livello di zona.

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

Dopo aver installato gke-gcloud-auth-plugin ed 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 client 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, 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 \
    --location=CONTROL_PLANE_LOCATION

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • CONTROL_PLANE_LOCATION: la località di Compute Engine del control plane del tuo cluster. Specifica una regione per i cluster a livello di regione o una zona per i cluster a livello di zona.

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 procedere. La modifica di questa variabile ti consente di utilizzare i comandi kubectl senza digitare il percorso completo.

    In alternativa, aggiungi la riga seguente alla posizione in cui la shell archivia 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 questo comando per caricare il file aggiornato. L'esempio seguente utilizza .bashrc:

    source ~/.bashrc

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

Problema: i comandi kubectl restituiscono l'errore "Connessione rifiutata"

Se i comandi kubectl restituiscono un errore "connessione rifiutata", 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 località di Compute Engine del control plane del tuo cluster. Specifica una regione per i cluster a livello di regione o una zona per i cluster a livello di zona.

Se non sai cosa inserire per il nome o la località 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 che la connettività al cluster sia attiva:

  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 località di Compute Engine del control plane del tuo cluster. Specifica una regione per i cluster a livello di regione o una zona per i cluster a livello di zona.
    • 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 tue 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 dall'output del comando precedente, completa uno dei seguenti passaggi:

Errore: i comandi kubectl restituiscono l'errore "Impossibile negoziare una versione 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 non risponde

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 dei nodi. Se hai fatto lo scale down del 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 tunnel SSH o proxy Konnectivity per abilitare la comunicazione sicura. Le sezioni seguenti descrivono i passaggi per la risoluzione dei problemi specifici per ogni servizio:

Risolvi 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 di Compute Engine che utilizzano immagini fornite da Google controllano regolarmente i metadati comuni del progetto e i metadati 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 tua rete Compute Engine per consentire l'accesso SSH dall'indirizzo IP del control plane a ciascun 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 nessuna di queste regole esiste, il control plane non può aprire 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 nuovamente 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 è vicina al limite di dimensione massima, 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 progetto eseguendo 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 il problema sia questo, 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.

Risolvi 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 che stai utilizzando il proxy Konnectivity, assicurati che gli agenti Konnectivity dispongano dell'accesso al firewall richiesto e che le policy di rete siano configurate 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: al momento della 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 verso il 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, potrebbe essere necessario modificarle 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 workload sulla porta 10250 dagli intervalli dei pod.
    • Traffico in uscita dagli intervalli di pod.

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

Modifica la policy di rete

Il proxy Konnectivity potrebbe avere problemi se la policy di rete del cluster esegue una delle seguenti operazioni:

  • Blocca il traffico in entrata dallo spazio dei nomi kube-system allo spazio dei nomi workload
  • Blocca il traffico in uscita verso il control plane del cluster sulla porta 8132

Quando il traffico in entrata è bloccato dalla policy 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 dalla policy di rete, i log di 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 mantenere la rete del cluster bloccata per tutti gli accessi esterni, tieni presente che funzionalità come queste non funzioneranno.

Per verificare se le regole in entrata o in uscita della policy di rete sono la causa del problema, trova le policy di rete nello spazio dei nomi interessato eseguendo il seguente comando:

kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

Per risolvere il problema relativo alla policy in entrata, aggiungi quanto segue al campo spec.ingress delle policy 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 in 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 policy di rete utilizza una combinazione di regole in entrata e in uscita, valuta la possibilità di modificarle entrambe.

Regola l'agente di IP masquerading

Il control plane del cluster accetta il traffico dagli agenti Konnectivity se l'indirizzo IP di origine rientra 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 assicurarti 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 IP masquerading.

Errore: i comandi kubectl non vanno a buon fine con l'errore "Nessun agente disponibile"

Quando esegui i 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 con 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 control plane di GKE e i nodi del cluster. In particolare, significa che konnectivity-server nel 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 individuare eventuali problemi di connessione. Se i pod hanno lo stato Running, controlla i log per verificare la presenza di problemi di connessione. Poiché il comando kubectl logs dipende da Konnectivity, utilizza Esplora log nella consoleCloud de Confiance :

      1. Nella console Cloud de Confiance , vai a Esplora log.

        Vai a Esplora log

      2. Nel riquadro delle 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 una policy di rete sta bloccando il traffico verso il control plane sulla porta TCP 8132 o sta bloccando il traffico tra l'agente Konnectivity e altri nodi. Gli errori di certificato indicano che un firewall o un proxy sta ispezionando e interferendo con il traffico TLS criptato.

    3. Indaga sul motivo per cui 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 potrebbe non funzionare.

      Le cause più comuni di un pod non in esecuzione sono:

      • Taint dei nodi personalizzati 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 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 dei service account, pertanto l'interferenza con le revisioni dei token può impedire la connessione degli agenti. 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 affinché il konnectivity-agent possa raggiungere il servizio Konnectivity. Per saperne di più, consulta Consenti l'accesso al firewall richiesto.

  4. Assicurati che non esistano regole delle policy di rete che limitano il traffico Konnectivity essenziale. Le regole della policy di rete devono consentire sia il traffico all'interno del cluster (da pod a pod) nello spazio dei nomi kube-system sia il traffico in uscita dai pod konnectivity-agent al control plane di GKE.

Risolvi i problemi di limitazione lato client di kubectl

Sintomo:

Quando utilizzi kubectl, potresti riscontrare una limitazione lato client, con messaggi di errore che contengono quanto segue: ...Throttling request took 1.002582473s, request: GET:... o Waited for 1.183040416s due to client-side throttling, not priority and fairness, request: GET: ....

Causa:

Quando esegui un comando kubectl, questo memorizza nella cache un elenco di risorse dal server API. Questo elenco corrisponde alle definizioni di risorse personalizzate (CRD) disponibili dal server API.

Quando un cluster GKE ha un numero elevato di CRD, ad esempio 300 o più, kubectl invia un numero elevato di richieste al server API per creare o aggiornare la propria cache. Per evitare di sovraccaricare il server API, kubectl si limita automaticamente.

Risoluzione:

Questi tipi di messaggi di errore di limitazione sono un comportamento previsto e sono causati dalla limitazione lato client sul lato kubectl. Il problema dovrebbe risolversi da solo.

Passaggi successivi