Installer kubectl et configurer l'accès au cluster

Cette page explique comment installer et configurer l'outil de ligne de commande kubectl pour interagir avec vos clusters Google Kubernetes Engine (GKE).

Aperçu

kubectl est un outil de ligne de commande que vous pouvez utiliser pour interagir avec vos clusters GKE. Pour utiliser kubectl avec GKE, vous devez installer l'outil et le configurer pour communiquer avec vos clusters. Une configuration kubectl supplémentaire est requise si vous exécutez plusieurs clusters dans Google Cloud.

Cette page vous montre les éléments suivants :

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

  • Assurez-vous d'avoir activé l'API Google Kubernetes Engine.
    • Activer l'API Google Kubernetes Engine
  • Assurez-vous d'avoir installé Google Cloud CLI.
  • Configurez les paramètres par défaut de Google Cloud CLI pour votre projet en utilisant l'une des méthodes suivantes :
    • Utilisez gcloud init si vous souhaitez suivre les étapes de définition des paramètres par défaut du projet.
    • Utilisez gcloud config pour définir individuellement l'ID, la zone et la région de votre projet.

    gcloud init

    1. Exécutez gcloud init et suivez les instructions :

      gcloud init

      Si vous utilisez SSH sur un serveur distant, utilisez l'option --console-only pour empêcher la commande d'ouvrir un navigateur :

      gcloud init --console-only
    2. Suivez les instructions pour autoriser gcloud CLI à utiliser votre compte Google Cloud.
    3. Créez ou sélectionnez une configuration.
    4. Choisissez un projet Google Cloud.
    5. Choisissez une zone Compute Engine par défaut.
    6. Choisissez une région Compute Engine par défaut.

    gcloud config

    1. Définissez votre ID de projet par défaut : 
      gcloud config set project PROJECT_ID
    2. Définissez votre région Compute Engine par défaut (par exemple, us-central1) : 
      gcloud config set compute/region COMPUTE_REGION
    3. Définissez votre zone Compute Engine par défaut (par exemple, us-central1-c) : 
      gcloud config set compute/zone COMPUTE_ZONE
    4. Mettez à jour gcloud vers la dernière version :
      gcloud components update

    En définissant des emplacements par défaut, vous pouvez éviter les erreurs gcloud CLI telles que celle-ci : One of [--zone, --region] must be supplied: Please specify location.

Installez kubectl.

Vous pouvez installer kubectl à l'aide de Google Cloud CLI ou d'un gestionnaire de packages externe tel que apt ou yum.

gcloud

  1. Installez le composant kubectl :

    gcloud components install kubectl

  2. Vérifiez que kubectl est installé :

    kubectl version

apt

  1. Vérifiez que vous avez bien le dépôt cloud-sdk :

    grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"

    Le résultat ressemble à ce qui suit :

    deb  [signed-by=/usr/share/keyrings/cloud.google.gpg]  https://packages.cloud.google.com/apt cloud-sdk main

  2. Installez le composant kubectl :

    apt-get update
apt-get install -y kubectl

  3. Vérifiez que kubectl est installé en validant qu'il s'agit bien de la dernière version :

    kubectl version --short --client

yum

  1. Vérifiez que vous avez bien le dépôt cloud-sdk :

    yum repolist | grep "google-cloud-sdk"

    Le résultat ressemble à ce qui suit :

    google-cloud-sdk    Google Cloud SDK    2,205

  2. Installez le composant kubectl :

    yum install -y kubectl

  3. Vérifiez que kubectl est installé :

    kubectl version --short --client

Installer les plug-ins requis

kubectl et d'autres clients Kubernetes nécessitent un plug-in d'authentification, gke- gcloud-auth-plugin, qui utilise le framework Client-go Credential Plugins pour fournir des jetons d'authentification afin de communiquer avec les clusters GKE.

Avant la publication de la version 1.25 de Kubernetes, gcloud CLI commencera à exiger que le binaire gke-gcloud-auth-plugin soit installé. Sans ce binaire, les installations existantes de kubectl ou d'autres clients Kubernetes personnalisés cesseront de fonctionner.

Vous devez installer ce plug-in pour utiliser kubectl et d'autres clients afin d'interagir avec GKE. Les clients existants affichent un message d'erreur si le plug-in n'est pas installé.

Avant de commencer, vérifiez si le plug-in est déjà installé :

gke-gcloud-auth-plugin --version

Si le résultat affiche des informations sur la version, ignorez cette section.

Vous pouvez installer le plug-in d'authentification à l'aide de gcloud CLI ou d'un gestionnaire de packages externe tel que apt ou yum.

gcloud

Installez le binaire gke-gcloud-auth-plugin :

  gcloud components install gke-gcloud-auth-plugin

apt

Installez le binaire gke-gcloud-auth-plugin :

  apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

yum

Installez le binaire gke-gcloud-auth-plugin :

  yum install google-cloud-sdk-gke-gcloud-auth-plugin

Vérifiez l'installation du binaire gke-gcloud-auth-plugin :

  1. Vérifiez la version du binaire gke-gcloud-auth-plugin :

    gke-gcloud-auth-plugin --version

  2. Mettez à jour la configuration de kubectl pour utiliser le plug-in :

    gcloud container clusters get-credentials CLUSTER_NAME

    Remplacez CLUSTER_NAME par le nom de votre cluster.

  3. Vérifiez la configuration :

    kubectl get namespaces

    Le résultat ressemble à ce qui suit :

    NAME              STATUS   AGE
default           Active   51d
kube-node-lease   Active   51d
kube-public       Active   51d
kube-system       Active   51d

Pour plus d'informations sur les raisons pour lesquelles ce plug-in est requis, consultez la page Kubernetes KEP.

Interagir avec kubectl

Kubernetes se sert d'un fichier YAML appelé kubeconfig pour stocker les informations d'authentification de cluster pour kubectl. Par défaut, le fichier est enregistré à l'emplacement $HOME/.kube/config.

kubeconfig contient un groupe de paramètres d'accès appelé contextes. Chaque contexte contient un cluster Kubernetes, un utilisateur et un espace de noms par défaut facultatif. kubectl fait référence aux contextes lors de l'exécution de commandes.

Voici les tâches que vous pouvez effectuer pour configurer kubectl :

  • Choisissez le cluster avec lequel kubectl doit communiquer.
  • Définissez un cluster par défaut pour kubectl en définissant le contexte actuel dans le fichier kubeconfig.
  • Exécutez des commandes kubectl sur un cluster spécifique à l'aide de l'option --cluster.

Afficher kubeconfig

Pour afficher le fichier kubeconfig de votre environnement, exécutez la commande suivante :

kubectl config view

La commande renvoie la liste des clusters pour lesquels des entrées kubeconfig ont été générées. Si un cluster GKE est répertorié, vous pouvez y exécuter des commandes kubectl dans votre environnement actuel. Sinon, vous devez stocker les informations du cluster pour kubectl.

Afficher le contexte actuel de kubectl

Le contexte actuel est le cluster par défaut actuel de kubectl. Toutes les commandes kubectl s'exécutent sur ce cluster.

Lorsque vous créez un cluster à l'aide de la commande gcloud container clusters create, une entrée s'ajoute automatiquement au fichier kubeconfig dans votre environnement, et le contexte actuel bascule sur ce cluster : Exemple :

gcloud container clusters create my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

Pour afficher le contexte actuel pour kubectl, exécutez la commande suivante :

kubectl config current-context

Stocker les informations du cluster pour kubectl

Lorsque vous créez un cluster à l'aide de Google Cloud Console ou de gcloud CLI depuis un autre ordinateur, le fichier kubeconfig de votre environnement n'est pas mis à jour. En outre, si un membre de l'équipe de projet se sert de gcloud CLI pour créer un cluster depuis son ordinateur, son fichier kubeconfig est mis à jour, mais pas le vôtre. L'entrée kubeconfig contient :

Pour générer un contexte kubeconfig dans votre environnement, vérifiez que vous disposez bien de l'autorisation container.clusters.get. Le rôle IAM au niveau d'accès le plus faible qui fournit cette autorisation est container.clusterViewer.

Pour générer un contexte kubeconfig pour un cluster spécifique, exécutez la commande suivante :

gcloud container clusters get-credentials CLUSTER_NAME

Remplacez CLUSTER_NAME par le nom de votre cluster.

Si le cluster cible ne s'exécute pas dans la zone ou la région par défaut, ou si vous n'avez pas défini de zone ou de région par défaut, vous devez indiquer la région (--region=REGION) ou la zone (--zone=ZONE) dans la commande.

Générer une entrée kubeconfig à l'aide de l'adresse IP interne d'un cluster privé

Tous les clusters possèdent un point de terminaison canonique. Le point de terminaison expose le serveur d'API Kubernetes utilisé par kubectl et d'autres services pour communiquer avec le plan de contrôle de votre cluster.

Les clusters privés ont deux adresses IP de point de terminaison distinctes : privateEndpoint, qui est une adresse IP interne, et publicEndpoint, qui est une adresse IP externe externe. Le champ endpoint fait référence à l'adresse IP externe, sauf si l'accès public au point de terminaison est désactivé. Dans ce cas, l'adresse IP privée est utilisée.

Pour les clusters privés, si vous préférez utiliser l'adresse IP interne comme point de terminaison, exécutez la commande suivante :

gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

Remplacez CLUSTER_NAME par le nom de votre cluster.

L'exécution de get-credentials utilise l'adresse IP spécifiée dans le champ endpoint par défaut.

Définir un cluster par défaut pour les commandes kubectl

Si vous avez déjà généré une entrée kubeconfig pour des clusters, vous pouvez basculer le contexte actuel de kubectl vers ce cluster en exécutant la commande suivante :

gcloud container clusters get-credentials CLUSTER_NAME

Remplacez CLUSTER_NAME par le nom de votre cluster.

Par exemple, imaginons un projet avec deux clusters, my-cluster et my-new- cluster. Le contexte actuel est my-new-cluster, mais vous souhaitez exécuter toutes les commandes kubectl sur my-cluster. Pour faire passer le contexte actuel de my-new-cluster à my-cluster, exécutez la commande suivante :

gcloud container clusters get-credentials my-cluster

Exécuter des commandes kubectl individuelles sur un cluster spécifique

Vous pouvez exécuter des commandes kubectl individuelles sur un cluster spécifique à l'aide de la commande --cluster=CLUSTER_NAME.

Par exemple, imaginons un environnement avec deux clusters, my-cluster et my- new-cluster, dans lequel le contexte actuel est my-cluster. Vous souhaitez déployer une application sur my-new-cluster, mais vous ne souhaitez pas modifier le contexte actuel. Pour déployer l'application sur my-new-cluster sans modifier le contexte actuel, exécutez la commande suivante :

kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster

Dépannage

Champs d'application d'authentification insuffisants

Lorsque vous exécutez gcloud container clusters get-credentials, vous obtenez 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 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.

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

Si l'erreur suivante s'affiche lorsque vous essayez d'exécuter kubectl ou que des clients personnalisés interagissent avec GKE, installez gke-gcloud-auth-plugin comme décrit dans les instructions d'installation. Les messages d'erreur sont semblables à ce qui suit :

  • Exemple d'erreur
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.
  • Exemple d'erreur
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

ERREUR : panique : aucun fournisseur d'authentification trouvé pour le nom gcp

L'erreur no Auth Provider found for name "gcp" est reçue si kubectl ou des clients Kubernetes personnalisés ont été créés avec Kubernetes client-go en version 1.25 ou ultérieure, comme décrit dans la section Fonctionnement. Pour résoudre ce problème, procédez comme suit :

  1. Installez gke-gcloud-auth-plugin comme décrit dans les instructions d'installation.

  2. Effectuez la mise à jour vers la dernière version de gcloud CLI à l'aide de gcloud components update.

  3. Mettez à jour le fichier kubeconfig.

    gcloud container clusters get-credentials CLUSTER_NAME

Remplacez CLUSTER_NAME par le nom de votre cluster.

Étape suivante

Faites l'essai

Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de GKE en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

Profiter d'un essai gratuit de GKE