Utiliser la passerelle Connect

Cette page vous explique comment utiliser la passerelle Connect pour vous connecter à un cluster enregistré. Avant de lire ce guide, vous devez vous familiariser avec les concepts de notre présentation. Ce guide part du principe que l'administrateur de votre projet a déjà configuré la passerelle, et qu'il vous a attribué les rôles et les autorisations nécessaires.

Avant de commencer

  • Assurez-vous que les outils de ligne de commande suivants sont installés :

    • La dernière version du SDK Cloud, qui inclut gcloud, l'outil de ligne de commande permettant l'interaction avec Google Cloud.
    • kubectl

    Si vous utilisez Cloud Shell comme environnement shell pour interagir avec Google Cloud, ces outils sont installés pour vous.

  • Assurez-vous d'avoir initialisé l'outil de ligne de commande gcloud à utiliser avec votre projet.

Connectez-vous à votre compte Google Cloud

Vous pouvez utiliser votre propre compte Google Cloud ou un compte de service Google Cloud pour interagir avec les clusters connectés via l'API Gateway.

Suivez les instructions de la section Autoriser les outils du SDK Cloud pour vous connecter à votre compte utilisateur. La passerelle Gateway permet l'emprunt d'identité du compte de service. Ainsi, même si vous êtes connecté à votre propre compte utilisateur, vous pouvez interagir avec les clusters à l'aide d'un compte de service, comme indiqué dans les sections suivantes.

Sélectionner un cluster enregistré

Si vous ne connaissez pas le nom du cluster auquel vous souhaitez accéder, vous pouvez afficher tous les clusters enregistrés de vos parcs en exécutant la commande suivante :

gcloud container hub memberships list

Cette commande répertorie tous les clusters de votre parc, y compris leurs noms d'appartenance et leurs ID externes. Chaque cluster d'un parc possède un nom d'appartenance unique. Pour les clusters GKE, le nom d'appartenance correspond généralement au nom que vous avez donné lors de la création du cluster, sauf si le nom du cluster n'était pas unique au sein de son projet à l'inscription.

Obtenir le fichier kubeconfig de la passerelle du cluster

Utilisez la commande suivante pour obtenir le kubeconfig dont vous avez besoin pour interagir avec le cluster spécifié, en remplaçant MEMBERSHIP_NAME par le nom d'appartenance du cluster de votre parc. Cette commande affiche un élément Connect kubeconfig spécifique à une passerelle qui vous permet de vous connecter au cluster via la passerelle.

# Fetch cluster credential used to interact with Connect gateway
gcloud container hub memberships get-credentials MEMBERSHIP_NAME

Si vous souhaitez utiliser un compte de service plutôt que votre propre compte Google Cloud, utilisez gcloud config pour définir auth/impersonate_service_account sur l'adresse e-mail du compte de service. Pour savoir comment permettre aux utilisateurs d'emprunter l'identité d'un compte de service, consultez la page Gérer l'emprunt d'identité d'un compte de service.

# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container hub memberships get-credentials MEMBERSHIP_NAME

Exécuter des commandes sur le cluster

Une fois que vous disposez des identifiants nécessaires, vous pouvez exécuter des commandes en utilisant kubectl ou go-client comme vous le feriez normalement pour tout cluster Kubernetes. Le résultat doit se présenter sous la forme suivante :

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

Les commandes kubectl suivantes ne sont pas acceptées par la passerelle :

  • exec
  • proxy

Dépannage

Si vous rencontrez des problèmes de connexion à un cluster via la passerelle, vous ou votre administrateur pouvez vérifier les problèmes courants ci-dessous.

  • Impossible de trouver des connexions actives pour le cluster (projet : 12345, appartenance : my-cluster) : cette erreur peut s'afficher lorsque l'agent Connect n'est plus connecté ou n'est pas installé (cela peut se produire pour les clusters GKE enregistrés sur Cloud Console ou avec Terraform/Config Connector). Pour résoudre ce problème, vous devez vérifier si l'espace de noms gke-connect existe sur le cluster. Si ce n'est pas le cas, consultez la section Enregistrer un cluster avec l'outil de ligne de commande gcloud. Si l'espace de noms gke-connect existe sur le cluster, consultez la page de dépannage de Connect pour résoudre les problèmes de connectivité.
  • Le serveur ne dispose pas du type de ressource "namespaces" : ce message d'erreur peut s'afficher lorsqu'une simple commande telle que kubectl get ns échoue. Plusieurs raisons peuvent expliquer cette erreur. Exécutez vos commandes kubectl en mode détaillé pour afficher plus de détails, par exemple kubectl get ns -v 10.
  • L'URL demandée est introuvable sur ce serveur : ce message d'erreur peut s'afficher lorsque kubeconfig contient une adresse de serveur incorrecte. Assurez-vous que la version du SDK Cloud que vous utilisez est la dernière version, puis réessayez de générer la passerelle kubeconfig. Ne modifiez pas manuellement le fichier kubeconfig, ce qui entraîne des erreurs inattendues.
  • L'identité de l'utilisateur ne dispose pas des autorisations nécessaires pour utiliser l'API de passerelle : vous devez disposer du rôle roles/gkehub.gatewayAdmin ou roles/gkehub.gatewayReaderpour utiliser l'API. Pour en savoir plus, consultez la section Accorder des autorisations IAM dans le guide de configuration de la passerelle.
  • L'agent Connect n'est pas autorisé à envoyer les requêtes de l'utilisateur : l'agent Connect doit être autorisé à transférer des requêtes en votre nom, conformément aux règles d'emprunt d'identité du cluster. Pour découvrir un exemple d'ajout d'un utilisateur au rôle gateway-impersonate, consultez la section Configurer les règles RBAC du guide de configuration de la passerelle.
  • L'identité de l'utilisateur ne dispose pas des autorisations RBAC suffisantes pour effectuer l'opération : vous devez disposer des autorisations appropriées sur le cluster pour exécuter les opérations choisies. Pour découvrir un exemple d'ajout d'un utilisateur au ClusterRole approprié, consultez la section Configurer les règles RBAC du guide de configuration de la passerelle.
  • L'agent Connect n'est pas opérationnel : consultez la page Dépannage des problèmes de connexion pour vous assurer que votre cluster est bien connecté.

Étape suivante

  • Découvrez un exemple d'utilisation de la passerelle Connect pendant votre automatisation DevOps dans notre tutoriel Intégration avec Cloud Build.