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 suppose que votre administrateur de projet a déjà configuré la passerelle et vous a accordé les rôles et 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 vos clusters enregistrés par Environ en exécutant la commande suivante :

gcloud container hub memberships list

Cette commande répertorie tous les clusters de votre Environ, y compris leurs noms d'appartenance et leurs ID externes. Chaque cluster d'un Environ est associé à 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 l'identifiant 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 Environ. Cette commande affiche un élément Connectkubeconfig 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 beta 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 beta 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 faites habituellement 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 rechercher les problèmes courants suivants.

  • Le serveur ne possède pas de type de ressource "namespaces" : ce message d'erreur peut s'afficher lorsqu'une commande simple telle que kubectl get ns échoue. Plusieurs raisons peuvent expliquer cette erreur. Exécutez vos commandes kubectl en mode verbeux pour obtenir 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 la passerelle d'API : vous devez disposer du rôle role/gkehub.gatewayAdmin pour 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 sélectionnées. 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.