Configurer l'accès au cluster pour kubectl

Cette page explique comment configurer l'accès au cluster pour l'outil de ligne de commande kubectl dans Google Kubernetes Engine.

Présentation

Si vous exécutez plusieurs clusters dans votre projet Google Cloud, vous devez choisir le cluster avec lequel kubectl doit communiquer. Vous pouvez définir un cluster par défaut pour kubectl en définissant le contexte actuel dans le fichier kubeconfig de Kubernetes. Vous pouvez également exécuter des commandes kubectl sur un cluster spécifique à l'aide de l'option --cluster.

Dans les sections suivantes, nous vous expliquons le fonctionnement de kubeconfig. Vous découvrirez également comment définir un cluster par défaut pour kubectl et comment exécuter des commandes kubectl individuelles sur un cluster spécifique.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

Configurez les paramètres gcloud par défaut à l'aide de l'une des méthodes suivantes :

  • Utilisez gcloud init pour suivre les instructions permettant de définir les paramètres par défaut.
  • Utilisez gcloud config pour définir individuellement l'ID, la zone et la région de votre projet.

Utiliser gcloud init

Si le message d'erreur One of [--zone, --region] must be supplied: Please specify location s'affiche, effectuez les tâches ci-dessous.

  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 à 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 pour les clusters zonaux ou une région pour les clusters régionaux ou Autopilot.

Utiliser gcloud config

  • Définissez votre ID de projet par défaut : 
    gcloud config set project PROJECT_ID
  • Si vous utilisez des clusters zonaux, définissez votre zone de calcul par défaut : 
    gcloud config set compute/zone COMPUTE_ZONE
  • Si vous utilisez des clusters Autopilot ou régionaux, définissez votre région de calcul par défaut : 
    gcloud config set compute/region COMPUTE_REGION
  • Mettez à jour gcloud vers la dernière version :
    gcloud components update

Fichier de configuration Kubernetes

Kubernetes se sert d'un fichier YAML appelé kubeconfig pour stocker les informations d'authentification de cluster pour kubectl. kubeconfig contient la liste des contextes auxquels kubectl fait référence lors de l'exécution de commandes. Par défaut, le fichier est enregistré sous $HOME/.kube/config.

Un contexte est un groupe de paramètres d'accès. Chaque contexte contient un cluster Kubernetes, un utilisateur et un espace de noms. 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 à kubeconfig dans votre environnement, et le contexte actuel bascule sur ce cluster :

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

Lorsque vous créez un cluster à l'aide de Google Cloud Console ou de la commande gcloud 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 pour créer un cluster depuis son ordinateur, son fichier kubeconfig est mis à jour, mais pas le vôtre. Suivez les instructions ci-dessous pour ajouter ces clusters à votre fichier kubeconfig local.

À propos du point de terminaison du cluster

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 (maître). L'adresse IP du point de terminaison s'affiche dans Cloud Console, dans le champ Points de terminaison de l'onglet "Détails" du cluster, et dans le résultat de gcloud container clusters describe dans le champ endpoint.

Lorsque vous exécutez gcloud container clusters get-credentials, vous constatez que la commande permet d'obtenir le point de terminaison du cluster dans le cadre de la mise à jour de kubeconfig.

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

L'exécution de get-credentials utilise l'adresse IP spécifiée dans le champ endpoint par défaut. Pour les clusters privés, si vous préférez utiliser l'adresse IP interne comme point de terminaison, reportez-vous à la section Générer une entrée kubeconfig à l'aide de l'adresse IP interne d'un cluster privé.

À propos de l'authentification pour kubectl

Tous les clusters GKE sont configurés pour accepter les identités de compte de service et de compte utilisateur Google Cloud, en validant les identifiants présentés par kubectl et en récupérant l'adresse e-mail associée à l'identité d'un utilisateur ou d'un compte de service. Par conséquent, les identifiants de ces comptes doivent inclure le champ d'application OAuth de userinfo.email afin de s'authentifier avec succès.

Lorsque vous utilisez gcloud pour configurer le fichier kubeconfig de votre environnement pour un nouveau cluster ou pour un cluster existant, gcloud fournit à kubectl les mêmes identifiants que ceux utilisés par gcloud. Par exemple, si vous utilisez la commande gcloud auth login, vos identifiants personnels sont fournis à kubectl, y compris le champ d'application userinfo.email. Cela permet au cluster GKE d'authentifier le client kubectl.

Vous pouvez également choisir de configurer kubectl pour utiliser les identifiants d'un compte de service Google Cloud lors de son exécution sur une instance Compute Engine. Toutefois, par défaut, le champ d'application userinfo.email n'est pas inclus dans les identifiants créés par les instances Compute Engine. Par conséquent, vous devez ajouter explicitement ce champ d'application, par exemple en utilisant l'option --scopes lors de la création de l'instance Compute Engine.

Une fois authentifiés, les comptes utilisateur ou de service Google Cloud doivent également être autorisés à effectuer des actions sur un cluster GKE. Consultez la page Contrôle des accès basé sur les rôles pour plus d'informations sur la configuration des autorisations.

Pour en savoir plus sur les méthodes d'authentification acceptées pour la connexion au serveur d'API Kubernetes, consultez la page S'authentifier auprès du serveur d'API Kubernetes.

Afficher le contexte actuel de kubectl

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

kubectl config current-context

Afficher le fichier 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 générer une entrée kubeconfig pour le cluster.

Générer une entrée kubeconfig

Pour exécuter des commandes kubectl sur un cluster créé dans Cloud Console depuis un autre ordinateur ou par un autre membre du projet, vous devez générer une entrée kubeconfig dans votre environnement.

Générez une entrée kubeconfig en exécutant la commande suivante :

gcloud container clusters get-credentials cluster-name

où cluster-name est le nom du cluster.

Pour exécuter cette commande, vous devez disposer 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.

L'entrée kubeconfig contient :

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

Lorsque vous exécutez get-credentials, vous pouvez spécifier à --internal-ip d'écrire l'adresse IP interne d'un cluster privé dans kubeconfig :

gcloud container clusters get-credentials --internal-ip cluster-name

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 :

gcloud container clusters get-credentials

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 basculer 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 en transmettant le nom du cluster tel qu'il apparaît dans kubeconfig en tant qu'argument pour l'option --cluster.

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.

É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