Ce guide explique comment déployer Agent Gateway pour le cross-cloud sur des clusters Kubernetes standards afin d'étendre la gouvernance de Gemini Enterprise Agent Platform à votre environnement. Pour une présentation de l'architecture à trois plans, consultez la présentation d'Agent Gateway pour le cross-cloud.
Avant de commencer
Avant de commencer, vérifiez que vous disposez des éléments suivants :
- Un cluster Kubernetes conforme à la Cloud Native Computing Foundation (CNCF).
- Un maillage de services ou une pile réseau existants configurés dans votre cluster.
- Connectivité réseau sortante de votre cluster vers les API Google Cloud via HTTPS (port TCP
443). - La version 591.0.0 ou ultérieure de la Google Cloud CLI doit être installée. Pour effectuer la mise à jour vers la dernière version, exécutez
gcloud components update. - Les rôles IAM (Identity and Access Management) sur votre projet Google Cloud dont vous avez besoin pour activer les API, créer un pool et un fournisseur d'identités de charge de travail, et accorder des rôles IAM.
Activer les API et enregistrer le cluster
Activez les API Google Cloud requises, puis enregistrez votre cluster externe.
Activer les API requises
Pour activer les API requises par Agent Gateway pour le cross-cloud, exécutez la commande suivante :
gcloud services enable \
agentregistry.googleapis.com \
apphubendpoint.googleapis.com \
cloudresourcemanager.googleapis.com \
cloudtrace.googleapis.com \
iam.googleapis.com \
iamcredentials.googleapis.com \
iap.googleapis.com \
logging.googleapis.com \
modelarmor.googleapis.com \
monitoring.googleapis.com \
networkservices.googleapis.com \
serviceextensions.googleapis.com \
sts.googleapis.com \
telemetry.googleapis.com \
trafficdirector.googleapis.com \
--project=PROJECT_ID
Remplacez PROJECT_ID par l'ID de votre projetGoogle Cloud .
Extraire la clé publique du serveur d'API Kubernetes
Pour enregistrer votre cluster, vous avez besoin de la clé publique qu'il utilise pour signer les jetons de compte de service. Pour extraire la clé publique, procédez comme suit :
Définissez votre contexte
kubectlactuel sur le cluster que vous souhaitez enregistrer.Récupérez le jeu de clés Web JSON (JWKS) de votre cluster, puis convertissez la première clé RSA en un fichier de clé publique nommé
pubkey.pem:kubectl get --raw /openid/v1/jwks > cluster-jwks.json N_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].n | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n') E_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].e | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n') openssl asn1parse -genconf <(printf "asn1=SEQUENCE:rsa_key\n[rsa_key]\nmodulus=INTEGER:0x%s\nexponent=INTEGER:0x%s\n" "$N_HEX" "$E_HEX") -noout -out /dev/stdout \ | openssl rsa -RSAPublicKey_in -inform DER -pubout -out pubkey.pemCes commandes nécessitent un shell Bash et les utilitaires
jqetopenssl.
Enregistrer le cluster
Pour enregistrer votre cluster, procédez comme suit :
Récupérez l'URL de l'émetteur OpenID Connect (OIDC) de votre cluster :
kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'
Le résultat est la valeur de l'option
--service-account-issuerdu serveur d'API Kubernetes de votre cluster. Cette valeur peut être différente de l'URL externe de votre serveur d'API Kubernetes. Copiez exactement le résultat. N'ajoutez pas ni ne supprimez de barre oblique finale.Enregistrez le cluster :
gcloud alpha network-services registered-clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --oidc-issuer-url=OIDC_ISSUER_URL \ --api-server-public-key="$(cat pubkey.pem)"Remplacez les éléments suivants :
CLUSTER_NAME: nom du cluster enregistré.PROJECT_ID: ID de votre projet Google Cloud.LOCATION: région Google Cloud du cluster enregistré, par exempleus-central1.OIDC_ISSUER_URL: URL exacte de l'émetteur que vous avez récupérée à l'étape précédente. L'URL doit commencer parhttps://.
Empêcher la suppression accidentelle de ressources
La suppression de votre projet Google Cloud ou l'annulation de l'enregistrement d'un cluster enregistré alors que des charges de travail cross-cloud sont actives déconnecte les contrôleurs du cluster et perturbe l'application des règles. Pour protéger vos ressources Google Cloud contre une suppression accidentelle, appliquez les mesures de protection suivantes :
- Protéger le projet Google Cloud avec des privilèges : appliquez un privilège de projet au projetGoogle Cloud qui héberge votre cluster enregistré, Agent Registry et les pools d'identités fédérées pour bloquer la suppression accidentelle du projet jusqu'à ce que tous les clusters cross-cloud soient mis hors service.
- Limiter les autorisations IAM destructives : limitez les autorisations permettant de supprimer des clusters enregistrés ou des ressources de passerelle (telles que
networkservices.registeredClusters.deleteetnetworkservices.agentGateways.delete) aux rôles d'administrateur de plate-forme dédiés. - Conserver les finaliseurs de ressources Kubernetes : ne supprimez pas les finaliseurs des ressources personnalisées du cluster gérées par le contrôleur
agent-governance-cross-cloud-controller. Les finaliseurs garantissent que les enregistrements du plan de contrôle Google Cloud correspondants sont correctement déprovisionnés avant la suppression des ressources du cluster local. - Supprimez les ressources personnalisées avant de supprimer le contrôleur : avant de désinstaller le chart Helm
agent-governance-cross-cloudou de supprimer votre cluster Kubernetes, supprimez toutes les ressources personnaliséesGCPExtensionBindingetGCPAgentGateway, puis attendez que la suppression soit terminée. Si vous supprimez d'abord le contrôleur, la ressource Agent Gateway correspondante reste orpheline dans Network Services. La passerelle orpheline bloque la suppression du modèle de connectivité de l'agent et du cluster enregistré.
Configurer la fédération d'identité de charge de travail
Les composants intégrés au cluster d'Agent Gateway pour le cross-cloud (le contrôleur agent-governance-cross-cloud-controller, le collecteur de télémétrie et le proxy) utilisent la fédération d'identité de charge de travail pour s'authentifier auprès des APIGoogle Cloud . Chaque composant échange son jeton de compte de service Kubernetes (KSA) contre un jeton d'accès fédéré. Vous attribuez des rôles IAM directement à ces identités fédérées. Vous n'avez donc pas besoin de créer des comptes de serviceGoogle Cloud ni de stocker des clés de compte de service dans votre cluster.
Le side-car Agent Identity Runtime (AIR) qui s'exécute avec chaque proxy utilise le pool d'identités de charge de travail pour fournir des identités SPIFFE à vos charges de travail d'agent. Ces identités sont les identités d'agent de vos agents. Les règles Model Armor et IAP identifient les agents par leur identité d'agent, et non par les identités fédérées des composants du cluster. Pour connaître le format du principal, consultez Identifier le principal d'agent.
Créer un pool d'identités de charge de travail et un fournisseur
Pour créer un pool d'identités de charge de travail et un fournisseur OIDC pour votre cluster, procédez comme suit :
Si l'URL de l'émetteur OIDC de votre cluster n'est pas accessible publiquement, enregistrez le jeu de clés Web JSON (JWKS) de votre cluster dans un fichier :
kubectl get --raw /openid/v1/jwks > cluster-jwks.json
Lorsque vous fournissez le JWKS au fournisseur, Google Cloud peut valider les jetons KSA sans se connecter à l'émetteur OIDC de votre cluster.
Créez un pool d'identités de charge de travail :
gcloud iam workload-identity-pools create POOL_ID \ --project=PROJECT_ID \ --location=global \ --display-name="POOL_DISPLAY_NAME"Créez un fournisseur OIDC dans le pool :
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \ --project=PROJECT_ID \ --location=global \ --workload-identity-pool=POOL_ID \ --issuer-uri=OIDC_ISSUER_URL \ --jwk-json-path=cluster-jwks.json \ --attribute-mapping="google.subject=assertion.sub,attribute.namespace=assertion['kubernetes.io']['namespace'],attribute.service_account=assertion['kubernetes.io']['serviceaccount']['name']"Ne spécifiez pas l'option
--allowed-audiences. Les composants cross-cloud demandent des jetons pour l'audience par défaut, qui correspond au nom complet de la ressource du fournisseur ://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID.
Remplacez les éléments suivants :
POOL_ID: ID du pool d'identités de charge de travail.PROJECT_ID: ID de votre projet Google Cloud .POOL_DISPLAY_NAME: nom à afficher pour le pool.PROVIDER_ID: ID du fournisseur OIDC.OIDC_ISSUER_URL: URL exacte de l'émetteur OIDC que vous avez récupérée lorsque vous avez enregistré le cluster. Cette valeur doit correspondre à celle que vous avez transmise à--oidc-issuer-url, y compris si elle se termine par une barre oblique finale.
Déployer le plan de contrôle
Utilisez le chart Helm fourni pour déployer le contrôleur au sein du cluster, agent-governance-cross-cloud-controller et le collecteur de télémétrie dans l'espace de noms geap-system.
Assurer la connectivité du contrôleur
Assurez-vous que le pare-feu, le proxy, les règles de sortie et les règles de réseau de votre cluster autorisent la connectivité suivante :
- APIGoogle Cloud : les pods du contrôleur
agent-governance-cross-cloud-controlleret le collecteur de télémétrie doivent disposer d'une connectivité HTTPS et gRPC sortante sur le port TCP443vers*.googleapis.com. - Serveur d'API Kubernetes : les pods du contrôleur doivent pouvoir accéder au serveur d'API Kubernetes pour surveiller les services, les charges de travail et les ressources personnalisées Kubernetes.
- Charges de travail de l'agent dans tous les espaces de noms : les pods du contrôleur doivent pouvoir appeler les pods de l'agent et du serveur MCP dans n'importe quel espace de noms du cluster. Le contrôleur récupère la fiche d'agent de chaque charge de travail d'agent pour enregistrer l'agent dans Agent Registry.
Attribuer des rôles IAM au contrôleur et au collecteur de télémétrie
Attribuez des rôles IAM aux identités fédérées du contrôleur agent-governance-cross-cloud-controller et du collecteur de télémétrie, qui s'exécutent dans l'espace de noms geap-system :
- Opérateur satellite (
roles/networkservices.satelliteOperator) - Rédacteur de télémétrie cloud (
roles/telemetry.writer)
Pour attribuer les rôles, exécutez la commande suivante :
for ROLE in \
roles/networkservices.satelliteOperator \
roles/telemetry.writer; do
gcloud projects add-iam-policy-binding PROJECT_ID \
--role="${ROLE}" \
--member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/geap-system"
done
Remplacez les éléments suivants :
PROJECT_ID: ID de votre projet Google Cloud .PROJECT_NUMBER: numéro de votre projet Google Cloud .POOL_ID: ID du pool d'identités de charge de travail.
Installer le chart Helm du plan de contrôle
Pour installer le plan de contrôle, procédez comme suit :
Installez le chart Helm
agent-governance-cross-clouddans l'espace de nomsgeap-system:helm upgrade --install agent-governance-cross-cloud \ oci://gcr.io/gke-release/agent-governance-cross-cloud \ --version 0.1.1-preview \ --namespace geap-system \ --create-namespace \ --set gcp.projectId=PROJECT_ID \ --set-string gcp.projectNumber=PROJECT_NUMBER \ --set-string gcp.orgId=ORGANIZATION_ID \ --set gcp.location=LOCATION \ --set gcp.registeredCluster=CLUSTER_NAME \ --set gcp.workloadIdentityPool=POOL_ID \ --set gcp.identityProvider=PROVIDER_IDRemplacez les éléments suivants :
PROJECT_ID: ID de votre projet Google Cloud .PROJECT_NUMBER: numéro de votre projet Google Cloud .ORGANIZATION_ID: ID de votre organisationGoogle Cloud . Si votre projet n'est pas associé à une organisation, omettez l'option--set-string gcp.orgId.LOCATION: région dans laquelle vous avez enregistré le cluster (par exemple,us-central1).CLUSTER_NAME: nom du cluster enregistré.POOL_ID: ID du pool d'identités de charge de travail.PROVIDER_ID: ID du fournisseur du pool d'identités de charge de travail.
Si les nœuds de votre cluster ont des rejets (par exemple, les nœuds arm64 sur la plupart des fournisseurs de services cloud, y compris Google Cloud, AWS et Azure), définissez les tolérances des pods dans la valeur Helm
k8s.tolerations. Les tolérances s'appliquent au contrôleur, au collecteur OpenTelemetry (OTel) et aux déploiements de passerelle créés par le contrôleur. Par exemple, enregistrez le code suivant sous le nomtolerations-values.yaml, puis ajoutez--values tolerations-values.yamlà la commande précédente :k8s: tolerations: - key: "kubernetes.io/arch" operator: "Equal" value: "arm64" effect: "NoSchedule"Attendez que le déploiement du contrôleur soit prêt :
kubectl rollout status deployment/agent-governance-cross-cloud-controller \ --namespace geap-system --timeout=180s
Déployer le plan de données
Déployez Agent Gateway pour le proxy cross-cloud (proxy Envoy) en créant une ressource personnalisée GCPAgentGateway. Le proxy inspecte le trafic et applique des règles pour les charges de travail de l'agent qu'il gère. Chaque proxy s'exécute avec un side-car Agent Identity Runtime (AIR) qui négocie les Workload Identity, les certificats Secret Discovery Service (SDS) et l'échange de jetons local pour le proxy.
Vous devez déployer Agent Gateway pour le cross-cloud dans un espace de noms dédié (par exemple, agent-gateway-system) qui ne contient pas de charges de travail d'agent, de serveurs MCP ni d'autres pods d'application. Une seule passerelle dans cet espace de noms dédié peut régir le trafic sortant des charges de travail des agents dans votre cluster.
Attribuer des rôles IAM à la passerelle
Attribuez des rôles IAM aux identités fédérées de l'Agent Gateway pour le proxy cross-cloud. La liaison s'applique à tous les KSA de l'espace de noms de la passerelle. Attribuez donc ces rôles pour chaque espace de noms de la passerelle :
- Client Traffic Director (
roles/trafficdirector.client) - Lecteur de point de terminaison App Hub (
roles/apphubendpoint.viewer) - Lecteur de registre d'agents (
roles/agentregistry.viewer) - Éditeur Service Extensions (
roles/serviceextensions.editor), qui permet au proxy d'appeler des appels de règles Service Extensions
Pour attribuer les rôles, exécutez la commande suivante :
for ROLE in \
roles/trafficdirector.client \
roles/apphubendpoint.viewer \
roles/agentregistry.viewer \
roles/serviceextensions.editor; do
gcloud projects add-iam-policy-binding PROJECT_ID \
--role="${ROLE}" \
--member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/GATEWAY_NAMESPACE"
done
Remplacez les éléments suivants :
PROJECT_ID: ID de votre projet Google Cloud .PROJECT_NUMBER: numéro de votre projet Google Cloud .POOL_ID: ID du pool d'identités de charge de travail.GATEWAY_NAMESPACE: espace de noms dédié à la passerelle. Cet espace de noms ne doit pas contenir de charges de travail d'agent.
Créer un modèle de connectivité d'agent
Chaque passerelle fait référence à un modèle de connectivité d'agent, qui est une ressourceGoogle Cloud faisant référence à votrecluster enregistré. Vous n'avez pas besoin de créer un modèle distinct pour chaque passerelle : vous pouvez mapper plusieurs passerelles à un seul modèle. Vous pouvez également créer plusieurs modèles pour le même cluster.
Si vous disposez déjà d'un modèle de connectivité d'agent pour votre cluster que vous souhaitez utiliser, passez à la section Créer la passerelle.
Pour créer un modèle de connectivité d'agent, procédez comme suit :
Enregistrez la définition de modèle suivante sous le nom
act.yaml:description: "Agent connectivity template for CLUSTER_NAME" agentCompute: K8S registeredCluster: "projects/PROJECT_ID/locations/LOCATION/registeredClusters/CLUSTER_NAME"
Importez le modèle :
gcloud alpha network-services agent-connectivity-templates import ACT_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --source=act.yaml
Remplacez les éléments suivants :
CLUSTER_NAME: nom du cluster enregistré.PROJECT_ID: ID de votre projet Google Cloud .LOCATION: région dans laquelle vous avez enregistré le cluster.ACT_NAME: nom du modèle de connectivité de l'agent.
Créer la passerelle
Pour créer la passerelle, procédez comme suit :
Si l'espace de noms de la passerelle n'existe pas déjà, créez-le :
kubectl create namespace GATEWAY_NAMESPACE
Remplacez
GATEWAY_NAMESPACEpar l'espace de noms dédié à la passerelle que vous avez utilisé lorsque vous avez attribué des rôles à la passerelle.Enregistrez le manifeste suivant sous le nom
agent-gateway.yaml:apiVersion: networkservices.googleapis.com/v1alpha1 kind: GCPAgentGateway metadata: name: GATEWAY_NAME namespace: GATEWAY_NAMESPACE spec: agentConnectivityTemplateUri: "projects/PROJECT_ID/locations/LOCATION/agentConnectivityTemplates/ACT_NAME"
Remplacez les éléments suivants :
GATEWAY_NAME: nom de la passerelle.GATEWAY_NAMESPACE: espace de noms dédié à la passerelle que vous avez utilisé lorsque vous avez attribué des rôles à la passerelle.PROJECT_ID: ID de votre projet Google Cloud .LOCATION: région du modèle de connectivité de l'agent. Cette région doit correspondre à celle où vous avez enregistré le cluster.ACT_NAME: nom du modèle de connectivité de l'agent.
Appliquez le fichier manifeste :
kubectl apply -f agent-gateway.yaml
Attendez que la passerelle soit déployée et prête :
kubectl wait --for=condition=Reconciled=True \ gcpagentgateway/GATEWAY_NAME \ -n GATEWAY_NAMESPACE \ --timeout=300sLorsque la passerelle est prête, la commande renvoie
gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met.Configurez votre maillage de services pour transférer le trafic sortant des agents, comme les requêtes de grand modèle de langage (LLM), de Model Context Protocol (MCP) et d'agent à agent (A2A), via la passerelle.
Ajouter des tolérances aux passerelles existantes
Si vous ajoutez la valeur Helm k8s.tolerations après avoir créé une ressource GCPAgentGateway, procédez comme suit pour que le contrôleur recrée le déploiement de la passerelle avec les nouvelles tolérances :
Exécutez la commande
helm upgrade --installde la section Installer le chart Helm du plan de contrôle avec--values tolerations-values.yaml.Supprimez le déploiement de passerelle existant :
kubectl delete deployment GATEWAY_NAME \ --namespace GATEWAY_NAMESPACERépétez cette étape pour chaque passerelle de votre cluster.
Redémarrez le contrôleur pour qu'il recrée le déploiement de la passerelle :
kubectl rollout restart deployment/agent-governance-cross-cloud-controller \ --namespace geap-system
Cette procédure n'affecte pas la ressource Google Cloud AgentGateway ni les ressources GCPExtensionBinding associées. Le trafic sortant via la passerelle est interrompu jusqu'à ce que le contrôleur recrée le déploiement de la passerelle.
Autoriser la connectivité sortante aux API Google
Assurez-vous que l'Agent Gateway pour les pods de proxy cross-cloud dispose d'une connectivité HTTPS et gRPC sortante vers *.googleapis.com sur le port TCP 443.
Configurer l'inspection TLS
Configurez l'inspection TLS (Transport Layer Security) pour vous assurer qu'Agent Gateway pour le cross-cloud peut inspecter et régir le trafic sortant.
Sécuriser le secret de l'autorité de certification d'inspection TLS
Agent Gateway pour le cross-cloud utilise une autorité de certification racine (CA) pour émettre les certificats qu'il présente lorsqu'il inspecte le trafic TLS sortant.
Le contrôleur crée cette autorité de certification lorsqu'il démarre. L'AC, y compris sa clé privée, est stockée dans des ressources Kubernetes Secret dans deux espaces de noms : l'espace de noms du contrôleur (geap-system) et l'espace de noms de la passerelle, où sont déployés l'Agent Gateway pour le proxy cross-cloud et le side-car AIR.
Toute personne pouvant lire ces ressources Secret peut emprunter l'identité de points de terminaison externes pour vos charges de travail d'agent. Pour protéger l'autorité de certification, appliquez les mesures de protection suivantes :
- Limiter l'accès RBAC à
Secret: limitez les autorisationsget,listetwatchsur les ressourcesSecretdans les espaces de nomsgeap-systemet de passerelle à Agent Gateway pour les comptes de service cross-cloud et les administrateurs de plate-forme dédiés. Les autorisationslistetwatchexposent également le contenu deSecret. - Isoler les espaces de noms du contrôleur et de la passerelle : les utilisateurs autorisés à créer des pods dans un espace de noms peuvent installer n'importe quel
Secretdans cet espace de noms. Exécutez uniquement Agent Gateway pour les composants cross-cloud dans l'espace de nomsgeap-systemet l'espace de noms de la passerelle. Ne déployez pas de charges de travail d'agent ni d'autres pods dans ces espaces de noms. Limitez les autorisations de création ou de modification des pods, des déploiements et d'autres ressources de charge de travail dans ces espaces de noms aux administrateurs de confiance. - Chiffrer les données
Secretau repos : activez le chiffrement au repos pour les ressourcesSecretdans le datastore etcd de votre cluster. Dans la mesure du possible, utilisez un fournisseur KMS pour gérer les clés de chiffrement. - Auditer l'accès à
Secret: activez la journalisation d'audit Kubernetes et surveillez l'accès en lecture à l'objetSecretde l'autorité de certification.
Étapes suivantes
- Déployer et enregistrer des agents cross-cloud
- Appliquer des règles de gouvernance cross-cloud
- Configurer l'observabilité des agents cross-cloud