Résoudre les problèmes liés à l'outil de ligne de commande kubectl

Cette page explique comment résoudre les problèmes liés à l'outil de ligne de commande kubectl lorsque vous travaillez dans Google Kubernetes Engine (GKE). Pour obtenir des conseils plus généraux, consultez la section Dépannage de kubectl dans la documentation Kubernetes.

Erreurs d'authentification et d'autorisation

Si vous rencontrez des erreurs liées à l'authentification et à l'autorisation lorsque vous utilisez les commandes de l'outil de ligne de commande kubectl, consultez les sections suivantes pour obtenir des conseils.

Erreur : 401 (Opération non autorisée)

Lorsque vous vous connectez à des clusters GKE, vous pouvez recevoir une erreur d'authentification et d'autorisation avec le code d'état HTTP 401 (Unauthorized). Ce problème peut se produire lorsque vous essayez d'exécuter une commande kubectl dans votre cluster GKE à partir d'un environnement local. Pour en savoir plus, consultez la section Problème : erreurs d'authentification et d'autorisation.

Erreur : champs d'application d'authentification insuffisants

Lorsque vous exécutez gcloud container clusters get-credentials, vous pouvez recevoir l'erreur suivante :

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

Cette erreur se produit car vous tentez d'accéder à l'API GKE à partir d'une VM Compute Engine qui ne possède pas le champ d'application cloud-platform.

Pour résoudre cette erreur, accordez l'étendue cloud-platform manquante. Pour savoir comment modifier les champs d'application sur votre instance de VM Compute Engine, consultez la section Créer et activer des comptes de service pour les instances dans la documentation Compute Engine.

Erreur : l'exécutable gke-gcloud-auth-plugin est introuvable

Des messages d'erreur semblables à ceux-ci peuvent s'afficher lorsque vous essayez d'exécuter des commandes kubectl ou des clients personnalisés qui interagissent avec GKE :

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

Pour résoudre le problème, installez gke-gcloud-auth-plugin comme décrit dans la section Installer les plug-ins requis.

Erreur : Aucun fournisseur d'authentification trouvé

L'erreur suivante se produit si kubectl ou des clients Kubernetes personnalisés ont été créés avec Kubernetes client-go version 1.26 ou ultérieure :

no Auth Provider found for name "gcp"

Pour résoudre ce problème, procédez comme suit :

  1. Installez gke-gcloud-auth-plugin comme décrit dans la section Installer les plug-ins requis.

  2. Effectuez la mise à jour vers la dernière version de gcloud CLI :

    gcloud components update

  3. Mettez à jour le fichier kubeconfig :

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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster
    • CONTROL_PLANE_LOCATION: emplacement Compute Engine du plan de contrôle de votre cluster. Indiquez une région pour les clusters régionaux ou une zone pour les clusters zonaux.

Erreur : Le plug-in d'authentification gcp est obsolète. Utilisez plutôt gcloud

Vous pouvez voir le message d'avertissement suivant après avoir installé gke-gcloud-auth-plugin et exécuté une commande kubectl sur un cluster GKE :

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

Ce message s'affiche si votre version du client est antérieure à la version 1.26.

Pour résoudre ce problème, demandez à votre client d'utiliser le plug-in d'authentification gke-gcloud-auth-plugin à la place :

  1. Ouvrez votre script de connexion shell dans un éditeur de texte :

    Bash

    vi ~/.bashrc

    Zsh

    vi ~/.zshrc

    Si vous utilisez PowerShell, ignorez cette étape.

  2. Définissez la variable d'environnement suivante :

    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. Appliquez la variable dans votre environnement :

    Bash

    source ~/.bashrc

    Zsh

    source ~/.zshrc

    PowerShell

    Quittez le terminal et ouvrez une nouvelle session de terminal.

  4. Mettre à jour gcloud CLI :

    gcloud components update

  5. S'authentifier sur votre cluster :

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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster
    • CONTROL_PLANE_LOCATION: emplacement Compute Engine du plan de contrôle de votre cluster. Indiquez une région pour les clusters régionaux ou une zone pour les clusters zonaux.

Problème : la commande kubectl est introuvable

Si vous recevez un message indiquant que la commande kubectl est introuvable, réinstallez le binaire kubectl et définissez votre variable d'environnement $PATH :

  1. Installez le binaire kubectl :

    gcloud components update kubectl

  2. Lorsque le programme d'installation vous invite à modifier votre variable d'environnement $PATH, saisissez y pour continuer. La modification de cette variable vous permet d'utiliser les commandes kubectl sans avoir à saisir leur chemin d'accès complet.

    Vous pouvez également ajouter la ligne suivante à l'emplacement où votre interface système stocke les variables d'environnement, par exemple ~/.bashrc (ou ~/.bash_profile sous macOS) :

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

  3. Exécutez la commande suivante pour charger votre fichier mis à jour. L'exemple suivant utilise .bashrc :

    source ~/.bashrc

    Si vous utilisez macOS, utilisez ~/.bash_profile au lieu de .bashrc.

Problème : les commandes kubectl renvoient une erreur de type "connexion refusée"

Si les commandes kubectl renvoient une erreur de type "connexion refusée", vous devez définir le contexte de cluster à l'aide de la commande suivante :

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

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom du cluster
  • CONTROL_PLANE_LOCATION: emplacement Compute Engine du plan de contrôle de votre cluster. Indiquez une région pour les clusters régionaux ou une zone pour les clusters zonaux.

Si vous ne savez pas quoi indiquer pour le nom ou l'emplacement du cluster, utilisez la commande suivante pour lister vos clusters:

gcloud container clusters list

Erreur : la commande kubectl a expiré

Si vous avez créé un cluster et que vous avez tenté d'exécuter une commande kubectl sur le cluster, mais que la commande kubectl a expiré, un message d'erreur semblable au suivant s'affiche :

  • 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.

Ces erreurs indiquent que kubectl ne parvient pas à communiquer avec le plan de contrôle du cluster.

Pour résoudre ce problème, vérifiez et définissez le contexte dans lequel le cluster est défini et assurez-vous de la connectivité au cluster :

  1. Accédez à $HOME/.kube/config ou exécutez la commande kubectl config view pour vérifier que le fichier de configuration contient le contexte du cluster et l'adresse IP externe du plan de contrôle.

  2. Définissez les identifiants du cluster:

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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster
    • CONTROL_PLANE_LOCATION: emplacement Compute Engine du plan de contrôle de votre cluster. Indiquez une région pour les clusters régionaux ou une zone pour les clusters zonaux.
    • PROJECT_ID : ID du projet dans lequel le cluster a été créé.

  3. Si vous avez activé les réseaux autorisés dans le cluster, assurez-vous que sa liste des réseaux autorisés existants inclut l'adresse IP sortante de la machine à partir de laquelle vous essayez de vous connecter. Les réseaux autorisés existants sont visibles dans la console ou au moyen de la commande suivante :

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

    Si l'adresse IP sortante de la machine ne figure pas dans la liste des réseaux autorisés à partir du résultat de la commande précédente, procédez comme suit :

Erreur : les commandes kubectl renvoient une erreur d'échec de négociation d'une version d'API

Si les commandes kubectl renvoient une erreur failed to negotiate an API version, vous devez vous assurer que kubectl dispose des identifiants d'authentification :

gcloud auth application-default login

Problème : la commande kubectl logs, attach, exec ou port-forward ne répond plus

Si les commandes kubectl logs, attach, exec ou port-forward cessent de répondre, le serveur d'API est généralement incapable de communiquer avec les nœuds.

Tout d'abord, vérifiez si votre cluster comporte des nœuds. Si vous avez réduit à zéro le nombre de nœuds du cluster, les commandes ne fonctionnent pas. Pour résoudre ce problème, redimensionnez votre cluster afin de disposer d'au moins un nœud.

Si votre cluster comporte au moins un nœud, vérifiez si vous utilisez des tunnels SSH ou proxy Konnectivity pour activer la communication sécurisée. Les sections suivantes décrivent les étapes de dépannage spécifiques à chaque service :

Résoudre les problèmes liés à SSH

Si vous utilisez SSH, GKE enregistre un fichier de clé publique SSH dans les métadonnées de votre projet Compute Engine. Toutes les VM Compute Engine utilisant des images fournies par Google vérifient régulièrement les métadonnées communes de leur projet et celles de leur instance pour détecter les clés SSH à ajouter à la liste des utilisateurs autorisés de la VM. GKE ajoute également à votre réseau Compute Engine une règle de pare-feu qui autorise l'accès SSH à chaque nœud du cluster à partir de l'adresse IP du plan de contrôle.

Les paramètres suivants peuvent entraîner des problèmes de communication SSH :

  • Les règles de pare-feu de votre réseau n'autorisent pas l'accès SSH depuis le plan de contrôle.

    Tous les réseaux Compute Engine sont créés avec une règle de pare-feu appelée default-allow-ssh qui autorise l'accès SSH à partir de toutes les adresses IP (clé privée valide requise). GKE insère également une règle SSH pour chaque cluster public sous la forme gke-CLUSTER_NAME-RANDOM_CHARACTERS-ssh. Cette règle autorise l'accès SSH spécifiquement à partir de l'adresse IP du plan de contrôle vers les nœuds du cluster.

    Si aucune de ces règles n'existe, le plan de contrôle ne peut pas ouvrir les tunnels SSH.

    Pour vérifier que c'est la cause du problème, vérifiez si votre configuration comporte ces règles.

    Pour résoudre ce problème, identifiez le tag présent sur tous les nœuds du cluster, puis ajoutez à nouveau une règle de pare-feu permettant d'accéder aux VM avec ce tag à partir de l'adresse IP du plan de contrôle.

  • L'entrée des métadonnées communes de votre projet pour ssh-keys est saturée.

    Si l'entrée des métadonnées du projet nommée ssh-keys est proche de sa limite de taille maximale, GKE ne peut pas ajouter sa propre clé SSH pour ouvrir des tunnels SSH.

    Pour vérifier qu'il s'agit bien du problème, vérifiez la longueur de la liste des ssh-keys. Vous pouvez voir les métadonnées de votre projet en exécutant la commande suivante, en incluant éventuellement l'indicateur --project :

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

    Pour résoudre ce problème, supprimez des clés SSH dont vous n'avez plus besoin.

  • Vous avez défini un champ de métadonnées avec la clé ssh-keys sur les VM du cluster.

    L'agent de nœud sur les VM utilise préférentiellement les clés SSH propres à une instance plutôt que celles définies à l'échelle du projet. Par conséquent, si vous avez défini des clés SSH spécifiquement sur les nœuds du cluster, la clé SSH du plan de contrôle dans les métadonnées du projet n'est pas respectée par les nœuds.

    Pour vérifier qu'il s'agit bien du problème, exécutez gcloud compute instances describe VM_NAME et recherchez un champ ssh-keys dans les métadonnées.

    Pour résoudre ce problème, supprimez les clés SSH par instance des métadonnées de l'instance.

Résoudre les problèmes liés au proxy Konnectivity

Vous pouvez déterminer si votre cluster utilise le proxy Konnectivity en vérifiant le déploiement système suivant :

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

Si votre cluster utilise le proxy Konnectivity, le résultat ressemble à ce qui suit:

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

Une fois que vous avez vérifié que vous utilisez le proxy Konnectivity, assurez-vous que les agents Konnectivity disposent de l'accès au pare-feu requis et que vos règles réseau sont configurées correctement.

Autoriser l'accès au pare-feu requis

Vérifiez que les règles de pare-feu de votre réseau autorisent l'accès aux ports suivants:

  • Port du plan de contrôle: lors de la création du cluster, les agents Konnectivity établissent des connexions au plan de contrôle sur le port 8132. Lorsque vous exécutez une commande kubectl, le serveur d'API utilise cette connexion pour communiquer avec le cluster. Assurez-vous d'autoriser le trafic de sortie vers le plan de contrôle du cluster sur le port 8132 (par exemple, le serveur d'API utilise le port 443). Si vous avez des règles qui refusent l'accès sortant, vous devrez peut-être les modifier ou créer des exceptions.

  • Port kubelet: étant donné que les agents Konnectivity sont des pods système déployés sur les nœuds de votre cluster, assurez-vous que vos règles de pare-feu autorisent les types de trafic suivants:

    • Trafic entrant vers vos charges de travail sur le port 10250 à partir de vos plages de pods.
    • Trafic sortant de vos plages de pods.

    Si vos règles de pare-feu n'autorisent pas ce type de trafic, modifiez-les.

Ajuster la règle de réseau

Le proxy Konnectivity peut rencontrer des problèmes si la règle de réseau de votre cluster:

  • Bloque l'entrée depuis l'espace de noms kube-system vers l'espace de noms workload.
  • Bloque la sortie vers le plan de contrôle du cluster sur le port 8132.

Lorsque l'entrée est bloquée par la stratégie réseau des pods de charge de travail, les journaux konnectivity-agent incluent un message d'erreur semblable à celui-ci:

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

Dans le message d'erreur, POD_IP_ADDRESS correspond à l'adresse IP du pod de la charge de travail.

Lorsque la sortie est bloquée par une règle réseau, les journaux konnectivity-agent incluent un message d'erreur semblable à celui-ci:

"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

Dans l'erreur, CP_IP_ADDRESS correspond à l'adresse IP du plan de contrôle du cluster.

Ces fonctionnalités ne sont pas nécessaires au bon fonctionnement du cluster. Si vous préférez empêcher tout accès extérieur au réseau de votre cluster, sachez que ces fonctionnalités ne sont pas opérationnelles.

Pour vérifier que les règles d'entrée ou de sortie des règles de réseau sont à l'origine du problème, recherchez les règles de réseau dans l'espace de noms concerné en exécutant la commande suivante:

kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

Pour résoudre le problème lié à la stratégie d'entrée, ajoutez le code suivant au champ spec.ingress des règles réseau:

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

Pour résoudre le problème lié à la règle de sortie, ajoutez le code suivant au champ spec.egress des règles réseau:

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

Si votre stratégie réseau utilise une combinaison de règles d'entrée et de sortie, envisagez d'ajuster les deux.

Ajuster l'agent de masquage d'adresses IP

Le plan de contrôle du cluster accepte le trafic des agents Konnectivity si l'adresse IP source se trouve dans les plages d'adresses IP des pods. Si vous modifiez la configuration de ip-masq-agent pour masquer l'adresse IP source du trafic vers le plan de contrôle du cluster, les agents Konnectivity peuvent rencontrer des erreurs de connectivité.

Pour résoudre le problème et vous assurer que le trafic des agents Konnectivity vers le plan de contrôle du cluster n'est pas masqué en tant qu'adresse IP du nœud, ajoutez l'adresse IP du plan de contrôle à la liste nonMasqueradeCIDRs dans le ConfigMap ip-masq-agent:

nonMasqueradeCIDRs:
- CONTROL_PLANE_IP_ADDRESS/32

Pour en savoir plus sur cette configuration, consultez la section Agent de masquage d'adresses IP.

Étapes suivantes