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'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 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 n'a pas de type de ressource: 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 détaillé pour afficher plus de détails, par exemple kubectl get ns -v 10.
Impossible de trouver des connexions actives pour cluster(projet: 12345, adhésion: mon-cluster): cette erreur peut s'afficher lorsque Connect Agent 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 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. Consultez la section Configurer l'autorisation RBAC dans le guide de configuration de la passerelle pour obtenir un exemple d'ajout d'un utilisateur au rôle gateway-impersonate.
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. Consultez la section Configurer l'autorisation RBAC dans le guide de configuration de la passerelle pour obtenir un exemple d'ajout d'un utilisateur au ClusterRole approprié.
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é.
executable gke-gcloud-auth-plugin not found ou no Auth Provider found for name gcp (Aucun fournisseur d'authentification trouvé pour le nom gcp) : la commande kubectl version 1.26 et ultérieure peut afficher cette erreur en raison de modifications apportées à la commande kubectl authentication depuis la version GKE 1.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 les anciennes versions de Google Cloud CLI : pour les clusters GKE, l'agent Connect n'est plus nécessaire au fonctionnement de la passerelle pour ne pas être installé par défaut lors de l'inscription. Les anciennes versions de Google Cloud CLI (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 anciennes versions peut échouer sur les clusters enregistrés avec une version plus récente de Google Cloud CLI. Pour résoudre ce problème, effectuez une mise à niveau de votre client Google Cloud CLI vers une version plus récente ou exécutez à nouveau la commande d'enregistrement d'adhésion 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.