Configurer Agent Gateway pour le cross-cloud

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 :

  1. Définissez votre contexte kubectl actuel sur le cluster que vous souhaitez enregistrer.

  2. 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.pem
    

    Ces commandes nécessitent un shell Bash et les utilitaires jq et openssl.

Enregistrer le cluster

Pour enregistrer votre cluster, procédez comme suit :

  1. 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-issuer du 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.

  2. 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 exemple us-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 par https://.

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.delete et networkservices.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-cloud ou de supprimer votre cluster Kubernetes, supprimez toutes les ressources personnalisées GCPExtensionBinding et GCPAgentGateway, 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 :

  1. 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.

  2. 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"
    
  3. 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-controller et le collecteur de télémétrie doivent disposer d'une connectivité HTTPS et gRPC sortante sur le port TCP 443 vers *.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 :

Installer le chart Helm du plan de contrôle

Pour installer le plan de contrôle, procédez comme suit :

  1. Installez le chart Helm agent-governance-cross-cloud dans l'espace de noms geap-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_ID
    

    Remplacez les éléments suivants :

    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 nom tolerations-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"
    
  2. 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 :

  1. 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"
    
  2. 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 :

  1. Si l'espace de noms de la passerelle n'existe pas déjà, créez-le :

    kubectl create namespace GATEWAY_NAMESPACE
    

    Remplacez GATEWAY_NAMESPACE par l'espace de noms dédié à la passerelle que vous avez utilisé lorsque vous avez attribué des rôles à la passerelle.

  2. 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 :

  3. Appliquez le fichier manifeste :

    kubectl apply -f agent-gateway.yaml
    
  4. Attendez que la passerelle soit déployée et prête :

    kubectl wait --for=condition=Reconciled=True \
        gcpagentgateway/GATEWAY_NAME \
        -n GATEWAY_NAMESPACE \
        --timeout=300s
    

    Lorsque la passerelle est prête, la commande renvoie gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met.

  5. 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 :

  1. Exécutez la commande helm upgrade --install de la section Installer le chart Helm du plan de contrôle avec --values tolerations-values.yaml.

  2. Supprimez le déploiement de passerelle existant :

    kubectl delete deployment GATEWAY_NAME \
        --namespace GATEWAY_NAMESPACE
    

    Répétez cette étape pour chaque passerelle de votre cluster.

  3. 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 autorisations get, list et watch sur les ressources Secret dans les espaces de noms geap-system et de passerelle à Agent Gateway pour les comptes de service cross-cloud et les administrateurs de plate-forme dédiés. Les autorisations list et watch exposent également le contenu de Secret.
  • 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 Secret dans cet espace de noms. Exécutez uniquement Agent Gateway pour les composants cross-cloud dans l'espace de noms geap-system et 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 Secret au repos : activez le chiffrement au repos pour les ressources Secret dans 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'objet Secret de l'autorité de certification.

Étapes suivantes