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 :

• comment fonctionne kubectl ;
• comment installer kubectl et toutes les dépendances requises ;
• comment définir un cluster par défaut pour kubectl ;
• comment exécuter des commandes kubectl sur un cluster spécifique.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

• Activez l'API Google Kubernetes Engine.
Activer l'API Google Kubernetes Engine
• Si vous souhaitez utiliser Google Cloud CLI pour cette tâche, installez puis initialisez gcloud CLI.
  Remarque : Pour les installations de gcloud CLI existantes, veillez à définir les propriétés compute/region et compute/zone. 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.26 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 la console Google Cloud 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 :

• vos identifiants, comme indiqué dans gcloud auth list, ou
• les identifiants par défaut de l'application, s'ils sont configurés.

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.

Remarque : L'exécution de gcloud container clusters get-credentials bascule également le contexte actuel de kubectl vers ce cluster.

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

Pour en savoir plus, consultez la section Résoudre les problèmes courants.

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

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

Vous pouvez voir ce message d'avertissement après avoir installé gke-gcloud-auth-plugin et exécuté une commande kubectl sur un cluster GKE. Ce message s'affiche si la version de votre client est antérieure à la version 1.26.

Pour indiquer à votre client d'utiliser le plug-in d'authentification gke-gcloud-auth-plugin, procédez comme suit:

1. Ouvrez votre script de connexion à l'interface système 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 à votre environnement:

   Bash

   source ~/.bashrc
   

   Zsh

   source ~/.zshrc
   

   PowerShell

   Quittez le terminal et ouvrez une nouvelle session de terminal.

4. Mettre à jour la CLI gcloud

   gcloud components update
   

5. S'authentifier sur votre cluster :

   gcloud container clusters get-credentials CLUSTER_NAME
   

   Remplacez CLUSTER_NAME par le nom de votre cluster. Cette commande force la configuration du cluster à utiliser le plug-in mis à jour pour s'authentifier.

Étapes suivantes

• Découvrez comment autoriser l'accès aux ressources des clusters GKE.
• Découvrez comment vous authentifier auprès des services Google Cloud avec des comptes de service.
• Consultez l'aide-mémoire sur kubectl.

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