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 :

  • Dernière version de Google Cloud CLI, l'outil de ligne de commande pour interagir 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é la CLI 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 Google Cloud CLI 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 fleet 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 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 container fleet 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'accès aux comptes 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 fleet 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
• port-forward
• attach

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.

• Le serveur ne possède pas de type de ressource : 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.
• Impossible de trouver des connexions actives pour le cluster (projet : 12345, appartenance : my-cluster) : cette erreur peut s'afficher lorsque l'agent Connect perd la connectivité ou n'est pas installé correctement. 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 Google Cloud CLI. 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é.
• 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 de Google Cloud CLI que vous utilisez est la dernière version et 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, roles/gkehub.gatewayReader ou roles/gkehub.gatewayEditor pour utiliser l'API. Pour en savoir plus, consultez la section Attribuer des rôles IAM aux utilisateurs 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 autorisations RBAC dans le 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 autorisations RBAC dans le guide de configuration de la passerelle.
• L'identité de l'utilisateur ne dispose pas des autorisations suffisantes pour effectuer l'opération lors de l'utilisation de Google Groupes ou d'une assistance tierce : Consultez la section Collecter les journaux de GKE Identity Service pour savoir comment inspecter les journaux associés aux informations d'identité.
• 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é.
• Exécutable gke-gcloud-auth-plugin introuvable ou aucun fournisseur d'authentification trouvé pour le nom gcp : les versions 1.26 et ultérieures de kubectl peuvent afficher cette erreur en raison de modifications apportées à l'authentification kubectl à partir de GKE v1.26. Installez gke-gcloud-auth-plugin et réexécutez gcloud container fleet memberships get-credentials MEMBERSHIP_NAME avec la dernière version de Google Cloud CLI.
• Les connexions à la passerelle échouent avec des versions plus anciennes de Google Cloud CLI : pour les clusters GKE, l'agent Connect n'est plus nécessaire pour que la passerelle fonctionne. Il n'est donc pas installé par défaut lors de l'enregistrement de l'appartenance. Les versions plus anciennes de Google Cloud CLI (versions 399.0.0 et antérieures) supposent l'existence de l'agent Connect sur le cluster. Toute tentative d'utilisation de la passerelle avec ces versions plus anciennes peut échouer sur les clusters enregistrés avec une version plus récente de Google Cloud CLI. Pour résoudre ce problème, mettez à niveau votre client Google Cloud CLI vers une version plus récente ou exécutez à nouveau la commande d'enregistrement de l'appartenance avec l'option --install-connect-agent.

Étape suivante

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