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 Résoudre les problèmes liés à 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 obtenir 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 Kubernetes Engine à partir d'une VM Compute Engine qui ne possède pas le champ d'application cloud-platform.

Pour résoudre cette erreur, accordez le champ d'application cloud-platform manquant. 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 \
    --region=COMPUTE_REGION

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster
    • COMPUTE_REGION : région Compute Engine du cluster. Pour les clusters zonaux, utilisez --zone=COMPUTE_ZONE.

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 \
    --region=COMPUTE_REGION

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster
    • COMPUTE_REGION : région Compute Engine du cluster. Pour les clusters zonaux, utilisez --zone=COMPUTE_ZONE.

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 la 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

Remplacez CLUSTER_NAME par le nom de votre cluster. Si vous ne savez pas quoi indiquer pour le nom 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=COMPUTE_LOCATION \
    --project=PROJECT_ID

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster
    • COMPUTE_LOCATION: emplacement Compute Engine.
    • PROJECT_ID : ID du projet dans lequel le cluster a été créé.

  3. Si le cluster est un cluster GKE privé, assurez-vous que sa liste de 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=COMPUTE_LOCATION \
    --project=PROJECT_ID \
    --format "flattened(masterAuthorizedNetworksConfig.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 le 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 la balise présente sur tous les nœuds du cluster, puis ajoutez à nouveau une règle de pare-feu permettant d'accéder aux VM avec cette balise à 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 de 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 de 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

Les paramètres suivants peuvent entraîner des problèmes avec le proxy Konnectivity :

  • Les règles de pare-feu de votre réseau n'autorisent pas l'agent Konnectivity à accéder au plan de contrôle.

    Lors de la création du cluster, les pods de l'agent Konnectivity établissent et maintiennent une connexion au plan de contrôle sur le port 8132. Lorsque l'une des commandes kubectl est exécutée, le serveur d'API utilise cette connexion pour communiquer avec le cluster.

    Si les règles de pare-feu de votre réseau contiennent une ou plusieurs règles de refus du trafic sortant, l'agent peut empêcher la connexion.

    Pour vérifier que c'est la cause du problème, vérifiez les règles de pare-feu de votre réseau afin de voir si elles contiennent une ou plusieurs règles de refus du trafic sortant.

    Pour résoudre ce problème, autorisez le trafic de sortie vers le plan de contrôle du cluster sur le port 8132. (Par exemple, le serveur d'API utilise 443.)

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

    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 c'est la cause 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 ce problème, ajoutez le code suivant au champ spec.ingress des règles réseau :

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

Étape suivante

Si vous avez besoin d'une aide supplémentaire, contactez Cloud Customer Care.