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é gcloud CLI à 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é:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Remplacez MEMBERSHIP_NAME par le nom d'appartenance du parc de votre cluster.

Cette commande affiche un élément kubeconfig spécifique à une passerelle Connect qui vous permet de vous connecter au cluster via la passerelle Connect.

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 récupérer les identifiants du cluster utilisés pour interagir avec la passerelle Connect à l'aide d'un compte de service, exécutez les commandes suivantes : Notez les points suivants:

• Clusters Google Distributed Cloud (logiciel uniquement) sur Bare Metal et VMware: le nom de l'appartenance est identique au nom du cluster.

• GKE sur AWS: utilisez gcloud container aws clusters get-credentials.

• GKE sur Azure: utilisez gcloud container azure clusters get-credentials.

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.

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Remplacez SA_EMAIL_ADDRESS par 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.

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

Limites

Les commandes kubectl suivantes ne sont pas compatibles avec la passerelle utilisant la commande gcloud container fleet memberships get-credentials:

• attach
• cp
• exec
• port-forward

Prise en charge des commandes en preview

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les commandes attach, cp et exec (mais pas port-forward) sont compatibles avec la commande bêta gcloud beta container fleet memberships get-credentials. Cette commande vous permet d'utiliser une fonctionnalité preview de la passerelle Connect.

Notez les exigences suivantes :

• GKE sur Google Cloud n'est pas compatible avec la version preview.

• Les clusters doivent être à la version 1.30 ou ultérieure.

• Le client kubectl doit être à la version 1.29 ou ultérieure. Si vous utilisez la version 1.29, vous devez définir la variable d'environnement suivante:

  export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true
  

  Les versions 1.30 et ultérieures de kubectl ne nécessitent pas de variable d'environnement.

  Pour vérifier la version de votre client, examinez le résultat de la commande kubectl version. Pour installer une version plus récente de kubectl, consultez la section Installer des outils.

Les utilisateurs et les comptes de service disposant du rôle IAM roles/gkehub.gatewayAdmin et du ClusterRole cluster-admin disposent des autorisations nécessaires pour exécuter les commandes attach, cp et exec. Si des utilisateurs et des comptes de service ont reçu un rôle IAM ou RBAC personnalisé, vous devrez peut-être accorder des autorisations supplémentaires. Pour plus d'informations, consultez les sections suivantes.

Accorder une autorisation supplémentaire si nécessaire

L'autorisation IAM gkehub.gateway.stream est requise pour exécuter les commandes attach, cp et exec via la passerelle Connect. Cette autorisation est incluse dans roles/gkehub.gatewayAdmin.

Pour les utilisateurs qui ne sont pas propriétaires du projet, ou pour les utilisateurs ou comptes de service qui ne disposent pas du rôle roles/gkehub.gatewayAdmin dans le projet, vous devez leur accorder le rôle roles/gkehub.gatewayAdmin ou créer un rôle personnalisé incluant les autres rôles requis et l'autorisation gkehub.gateway.stream. Pour savoir comment créer un rôle personnalisé, consultez la page Créer et gérer des rôles personnalisés dans la documentation IAM.

Créer et appliquer des règles RBAC supplémentaires si nécessaire

Les utilisateurs et les comptes de service disposant du ClusterRole cluster-admin disposent des autorisations nécessaires pour exécuter les commandes attach, cp et exec.

Les règles suivantes sont nécessaires pour exécuter les commandes:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE  # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE  # Specify the namespace
roleRef:
   apiGroup: "rbac.authorization.k8s.io"
   kind: Role
   name: stream-role
subjects:
- kind: User
  name: EMAIL # Specify the user that should have stream access
  namespace: NAMESPACE  # Specify the namespace

Résoudre les problèmes liés à kubectl exec/cp/attach

L'erreur renvoyée par l'exécution de la commande n'est souvent pas assez claire pour déboguer le problème. Dans ce cas, réexécutez la commande avec un niveau de journalisation plus détaillé, par exemple: kubectl exec -v 5 ....

La version bêta de la passerelle Connect n'est pas utilisée

Si vous obtenez une erreur 400 Bad Request, générez à nouveau le fichier kubeconfig de la passerelle de connexion à l'aide de la version bêta de gcloud CLI pour voir si cela résout l'erreur:

gcloud beta container fleet memberships get-credentials my-membership`

Si l'erreur 400 Bad Request s'affiche toujours, suivez la procédure décrite dans la section suivante.

L'option d'environnement kubectl n'est pas définie

Si la version du client kubectl que vous utilisez est la version 1.29, la variable d'environnement KUBECTL_REMOTE_COMMAND_WEBSOCKETS doit être activée. Si cette option n'est pas activée, une erreur 400 Bad Request s'affiche. Pour vérifier si la variable d'environnement est activée, exécutez la commande suivante:

 echo $KUBECTL_REMOTE_COMMAND_WEBSOCKETS`

Si la variable n'est pas définie, activez-la en définissant la variable d'environnement suivante:

export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

kubectl version 1.30 et versions ultérieures ne nécessite pas cet option, car elle est activée par défaut.

Les versions de kubectl antérieures à la version 1.29 ne sont pas compatibles avec cette fonctionnalité.

Autorisations IAM manquantes

Si vous recevez le message error: error reading from error stream..., cela peut indiquer que vous ne disposez pas des autorisations IAM requises pour exécuter la commande. Cette fonctionnalité nécessite que les utilisateurs disposent de l'autorisation IAM gkehub.gateway.stream, qui est incluse par défaut dans le rôle roles/gkehub.gatewayAdmin. Pour obtenir des instructions, consultez la section sur les autorisations IAM.

Message d'erreur generic::failed_precondition: erreur rencontrée dans le cluster

Si l'erreur generic::failed_precondition: error encountered within the cluster s'affiche, consultez les journaux de l'agent Connect dans le cluster pour identifier la cause sous-jacente:

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

Le journal à rechercher dans l'agent Connect est failed to create the websocket connection....

Autorisations RBAC obligatoires manquantes

Si le message d'erreur dans les journaux de l'agent Connect contient 403 Forbidden, cela signifie que vous ne disposez pas des autorisations RBAC. Vous disposez d'un ensemble d'autorisations RBAC dans le cluster pour exécuter ces commandes kubectl. Consultez la section Règles RBAC pour configurer les autorisations RBAC requises.

Message d'erreur generic::resource_exhausted: quota active_streams de la passerelle épuisé

Le quota est limité à 10 flux actifs par projet hôte du parc. Cette valeur est définie dans le quota connectgateway.googleapis.com/active_streams. Pour savoir comment gérer vos quotas, consultez Afficher et gérer les quotas.

Message d'erreur generic::failed_precondition: échec/fin de la connexion à l'agent

Si cette erreur s'affiche immédiatement lorsque vous exécutez la commande, cela signifie qu'il y a un problème de connexion du cluster à Google. Pour en savoir plus, consultez le guide de dépannage général.

Si vous rencontrez cette erreur après 5 à 10 minutes d'activité de la session, il s'agit d'une limitation attendue de la fonctionnalité. La connexion doit être rétablie.

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 lorsque la commande 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 (clusters en dehors de Google Cloud uniquement). Pour résoudre ce problème, vous devez vérifier si l'espace de noms gke-connect existe sur le cluster. 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înera 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.