Résoudre les problèmes liés à Agent Gateway

Lorsqu'une requête sortante de votre agent Cloud Run échoue ou contourne Agent Gateway, suivez le chemin de la requête à l'aide des vérifications suivantes ou consultez Problèmes courants et solutions. Pour obtenir des instructions de configuration, consultez Gérer les agents avec Agent Gateway.

Avant que le trafic n'atteigne Agent Gateway, le side-car Cloud Run Envoy récupère la configuration de routage et de certificat à partir de l'API Traffic Director. Le side-car envoie le trafic sortant via un tunnel mTLS CONNECT vers le proxy Web sécurisé.

Vérifier le routage sortant dans les journaux d'accès du side-car Envoy

Lorsque le side-car Envoy Cloud Run intercepte une connexion TCP sortante, il écrit une entrée de journal d'accès JSON dans run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log avec le champ jsonPayload.upstream_host.

Déclenchez une requête sortante depuis votre service Cloud Run et interrogez les journaux d'accès du side-car :

gcloud logging read \
    'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND jsonPayload.upstream_host:*' \
    --project=PROJECT_ID \
    --freshness=7d \
    --limit=20 \
    --format="table(timestamp, jsonPayload.sni, jsonPayload.upstream_host, jsonPayload.response_flags, jsonPayload.bytes_sent, jsonPayload.bytes_received, jsonPayload.duration)"

Remplacez les éléments suivants :

  • SERVICE_NAME : nom de votre service d'agent Cloud Run.
  • PROJECT_ID : ID de votre projet Google Cloud .

Une connexion opérationnelle via la passerelle renvoie un résultat semblable à celui-ci :

TIMESTAMP                     SNI          UPSTREAM_HOST                      RESPONSE_FLAGS  BYTES_SENT  BYTES_RECEIVED  DURATION
2026-10-09T05:07:48.340693Z   example.com  envoy://tunnel_internal_listener/  -               4101        2899            489

Vérifiez les valeurs UPSTREAM_HOST et RESPONSE_FLAGS :

  • Si UPSTREAM_HOST est envoy://tunnel_internal_listener/ et RESPONSE_FLAGS est -, la connexion est opérationnelle. Le side-car Envoy a mis en correspondance votre règle EgressRouting et a transféré la connexion à Agent Gateway.
  • Si UPSTREAM_HOST est une adresse IP et un port de destination tels que 93.184.216.34:443, l'API Traffic Director n'a pas pu faire correspondre votre règle EgressRouting ni résoudre la passerelle cible. Envoy a utilisé le passthrough ORIGINAL_DST et a contourné Agent Gateway. Consultez Auditer les URI des ressources EgressRouting et AgentGateway.
  • Si UPSTREAM_HOST est envoy://tunnel_internal_listener/ et que RESPONSE_FLAGS est UF ou UH, ou que BYTES_RECEIVED est 0, Envoy n'a pas pu ouvrir le tunnel CONNECT vers Secure Web Proxy. Vérifiez la connectivité de votre sous-réseau de cloud privé virtuel (VPC) ou consultez La mise à jour de la passerelle Secure Web Proxy interrompt le tunneling Envoy.
  • Si aucune ligne n'apparaît, vérifiez run.googleapis.com%2Frequests pour confirmer que la requête a atteint votre conteneur Cloud Run. Vérifiez que votre révision active active --ambient-networking. Si les lignes n'apparaissent toujours pas, consultez la section Vérifier les journaux de connexion et xDS du side-car Envoy.

Vérifier les journaux de connexion et xDS du side-car Envoy

Si les journaux d'accès du side-car Envoy ne renvoient aucune entrée ou indiquent un échec de connexion, inspectez les journaux de connexion xDS et en amont du side-car :

  1. Recherchez les erreurs de flux xDS de l'API Traffic Director ou l'état de démarrage :

    gcloud logging read \
   'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (severity>=INFO OR textPayload:"DeltaAggregatedResources")' \
   --project=PROJECT_ID \
   --freshness=7d \
   --limit=30 \
   --format="table(timestamp, severity, textPayload, jsonPayload.message)"

  2. Vérifiez les tentatives de connexion du tunnel en amont à ambient-swp-connect-cluster :

    gcloud logging read \
   'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (textPayload:"ambient-swp-connect-cluster" OR jsonPayload.message:"ambient-swp-connect-cluster" OR jsonPayload.message:"tunnel_internal_listener")' \
   --project=PROJECT_ID \
   --freshness=7d \
   --limit=30 \
   --format="table(timestamp, severity, textPayload, jsonPayload.message)"

    Remplacez les éléments suivants :

    • SERVICE_NAME : nom de votre service d'agent Cloud Run.
    • PROJECT_ID : ID de votre projet Google Cloud .

Vérifiez les messages de journal :

  • Si les journaux contiennent DeltaAggregatedResources gRPC config stream et The caller does not have permission, l'identité du service ne dispose pas de l'autorisation roles/trafficdirector.client. Consultez Le side-car Envoy ne peut pas recevoir la configuration xDS.
  • Si les journaux contiennent Creating connection to cluster ambient-swp-connect-cluster, Envoy a reçu la configuration EgressRouting et a tenté de se connecter à Secure Web Proxy.

Auditer les URI des ressources EgressRouting et AgentGateway

Lorsque vous exécutez gcloud alpha network-services egress-routings create ou gcloud beta network-services agent-gateways import, l'API valide la syntaxe de l'URI sans vérifier si les ressources cibles existent. Une faute de frappe dans un nom de ressource ou une région entraîne l'API Traffic Director à ignorer la traduction EgressRouting, et Envoy utilise le routage passthrough.

Inspectez les URI stockés et comparez-les à vos ressources déployées :

  1. Inspectez la ressource EgressRouting. Le résultat normalise les ID de projet en numéros de projet :

    gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \
   --location=REGION \
   --project=PROJECT_ID

  2. Répertoriez toutes les ressources EgressRouting de la région pour vérifier qu'aucune règle en double ne cible le même service :

    gcloud alpha network-services egress-routings list \
   --location=REGION \
   --project=PROJECT_ID

  3. Vérifiez que la passerelle Secure Web Proxy cible correspond à l'URI dans EgressRouting.gateway et AgentGateway.selfManaged.resourceUris :

    gcloud network-services gateways describe SWP_NAME \
   --location=REGION \
   --project=PROJECT_ID

    Remplacez les éléments suivants :

    • EGRESS_ROUTING_NAME : nom de votre ressource EgressRouting.
    • REGION : région de votre déploiement.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • SWP_NAME : nom de votre passerelle Secure Web Proxy.

Vérifiez que les trois URI correspondent à l'ID ou au numéro de votre projet, à la région et au nom de la ressource :

  • EgressRouting.sources[].workloadUri :
    • Champ d'application du service : //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
    • À l'échelle du projet : //run.googleapis.com/projects/PROJECT_ID ou //run.googleapis.com/projects/PROJECT_NUMBER
  • EgressRouting.gateway : //networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME
  • AgentGateway.selfManaged.resourceUris[] : projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME

Vérifier les journaux de transactions du proxy Web sécurisé

Si le side-car Envoy transfère le trafic vers Secure Web Proxy, mais que les requêtes échouent, inspectez les journaux de votre proxy comme décrit dans Afficher les journaux des transactions du proxy :

  • Si aucun trafic n'apparaît dans les journaux du proxy, cela signifie que les requêtes n'atteignent pas Secure Web Proxy. Vérifiez votre configuration EgressRouting dans Auditer les URI des ressources EgressRouting et AgentGateway et Problèmes courants et solutions.
  • Si vous constatez des décisions DENY ou ALLOW inattendues, vérifiez jsonPayload.authzPolicyInfo et jsonPayload.agentGatewayInfo dans l'entrée de journal pour inspecter les métadonnées AuthzPolicy et de destination correspondantes, et vérifiez toutes les règles ExtensionBinding associées à votre ressource Agent Gateway. Après avoir créé ou mis à jour une ressource ExtensionBinding, les modifications de configuration peuvent prendre jusqu'à cinq minutes pour se propager à la passerelle.

Problèmes courants et solutions

Les sections suivantes décrivent les problèmes courants et comment les résoudre.

Le trafic sortant contourne Agent Gateway en raison d'un URI de ressource non concordant

Le trafic sortant de Cloud Run contourne Agent Gateway ou expire après la réussite de egress-routings create. Dans envoy_sidecar_log, jsonPayload.upstream_host affiche l'adresse IP et le port de destination au lieu de envoy://tunnel_internal_listener/.

L'un des URI de ressource EgressRouting ou AgentGateway fait référence à un nom de ressource inexistant ou à une région incompatible. Lorsque l'API Traffic Director ne peut pas résoudre la chaîne du service Cloud Run vers Secure Web Proxy, elle ignore la traduction du tunnel et diffuse ORIGINAL_DST.

Exécutez les commandes de la section Auditer les URI des ressources EgressRouting et AgentGateway pour trouver l'URI non concordant. Mettez à jour la configuration avec le nom et la région de la ressource correspondante, puis recréez la ressource AgentGateway ou EgressRouting.

Le side-car Envoy ne peut pas recevoir la configuration xDS

Les requêtes sortantes du conteneur Cloud Run expirent ou échouent, et envoy_sidecar_log contient l'erreur suivante :

DeltaAggregatedResources gRPC config stream to trafficdirector.REGION.rep.googleapis.com:443 closed: 7, The caller does not have permission

L'identité du service d'exécution Cloud Run ne dispose pas de roles/trafficdirector.client. Par défaut, le déploiement d'un service avec --functional-type=agent et --identity-type=agent-identity accorde roles/run.agentDefaultAccess, qui inclut roles/trafficdirector.client et roles/cloudtrace.agent. Si votre identité de service ne dispose pas de ces autorisations, attribuez les rôles suivants :

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/cloudtrace.agent"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • ORGANIZATION_ID : ID de votre organisation Google Cloud .
  • PROJECT_NUMBER : numéro de votre projet Google Cloud .
  • REGION : région de votre service.
  • SERVICE_NAME : nom de votre service d'agent Cloud Run. Si votre service utilise un compte de service au lieu de l'identité de l'agent, définissez --member sur serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

Vérifiez que l'agent de service Cloud Run peut accéder à votre réseau VPC. Par défaut, roles/run.serviceAgent inclut ces autorisations. Si vous avez modifié les autorisations de l'agent de service, accordez roles/compute.networkUser :

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
    --role="roles/compute.networkUser"

La mise à jour de la passerelle Secure Web Proxy interrompt le tunneling Envoy

Après avoir mis à jour le ServerTlsPolicy, le certificat, l'adresse IP ou le port d'une passerelle Secure Web Proxy existante, les requêtes sortantes échouent avec des erreurs 502, 503 ou 504, ou envoy_sidecar_log signale RESPONSE_FLAGS: UF.

Vous ne pouvez pas modifier addresses ni ports après avoir créé une passerelle Secure Web Proxy. De plus, les mises à jour de serverTlsPolicy ou certificateUrls sur une passerelle Secure Web Proxy existante ne sont pas propagées aux points de terminaison EgressRouting dans l'API Traffic Director.

Pour modifier ces champs Secure Web Proxy sans temps d'arrêt de la charge de travail, procédez comme suit :

  1. Créez une passerelle Secure Web Proxy de remplacement avec un nom de ressource différent et la configuration mise à jour.
  2. Mettez à jour selfManaged.resourceUris dans la ressource AgentGateway pour référencer l'URI de la passerelle Secure Web Proxy de remplacement.
  3. Recréez votre ressource EgressRouting pour qu'elle pointe vers la passerelle Secure Web Proxy de remplacement.
  4. Une fois que la passerelle de remplacement achemine le trafic, supprimez l'ancienne passerelle Secure Web Proxy de la ressource AgentGateway et supprimez l'ancienne passerelle Secure Web Proxy.

Le proxy Web sécurisé refuse tout le trafic sortant

Toutes les requêtes sortantes de votre agent Cloud Run échouent avec des erreurs 403 après la création d'une règle EgressRouting ou l'association d'un ExtensionBinding.

Secure Web Proxy refuse tout le trafic par défaut jusqu'à ce qu'une ALLOW AuthzPolicy sur votre ressource Agent Gateway l'autorise. L'association d'un ExtensionBinding n'autorise pas le trafic sans AuthzPolicy ALLOW, et les règles associées à la ressource Gateway Secure Web Proxy sous-jacente sont ignorées.

Pour autoriser le trafic autorisé, associez une AuthzPolicy ALLOW qui cible votre ressource Agent Gateway. Pour obtenir des instructions, consultez Autoriser le trafic de sortie de référence et le trafic MCP.

Les requêtes de modèle sortantes échouent avec des erreurs 403

Les appels sortants de votre agent Cloud Run vers des points de terminaison de modèle tels que Vertex AI sur REGION-aiplatform.googleapis.com échouent avec des erreurs 403 Forbidden après la configuration des règles sur Agent Gateway.

Étant donné que --vpc-egress=all achemine tout le trafic sortant des conteneurs via Secure Web Proxy, les requêtes de modèle échouent si votre ALLOW AuthzPolicy ne correspond qu'aux méthodes MCP (Model Context Protocol) ou si votre ExtensionBinding Identity-Aware Proxy (IAP) correspond à des hôtes non MCP sans règle d'autorisation dans votre stratégie d'accès unifié IAM (Identity and Access Management).

Pour autoriser les appels de modèle sortants, autorisez vos points de terminaison de modèle dans un ALLOW AuthzPolicy sur votre ressource Agent Gateway. De plus, limitez le champ d'application de matchConditions dans votre ExtensionBinding IAP à prefix: "urn:mcp" ou ajoutez une règle d'autorisation destination.unregistered.host dans votre stratégie d'accès unifiée IAM. Pour obtenir des instructions, consultez Autoriser le trafic de sortie de référence et le trafic MCP et Configurer des règles de sortie IAP.

Secure Web Proxy ignore les ressources GatewaySecurityPolicyRules

Vous avez créé GatewaySecurityPolicyRules ou associé un AuthzPolicy sur la ressource Secure Web Proxy Gateway, mais ils n'ont aucun effet sur le trafic sortant de l'agent.

Lorsque Secure Web Proxy est associé à une ressource AgentGateway, il n'applique que les règles d'autorisation et les liaisons d'extension associées à la ressource AgentGateway. Toutes les ressources GatewaySecurityPolicyRules ou AuthzPolicy associées au Gateway Secure Web Proxy sous-jacent sont ignorées.

Associez plutôt vos ressources AuthzPolicy et ExtensionBinding à votre ressource Agent Gateway. Pour obtenir des instructions, consultez Configurer des règles sur Agent Gateway.

Échec de l'inspection TLS des requêtes sortantes

Les requêtes sortantes de votre agent Cloud Run échouent avec des erreurs TLS à chaque connexion.

Le compte de service Secure Web Proxy ne dispose pas de l'autorisation roles/privateca.certificateManager sur votre pool Certificate Authority Service.

Accordez roles/privateca.certificateManager sur le pool d'autorités de certification à votre compte de service Secure Web Proxy. Pour savoir comment procéder, consultez la section Créer un compte de service.

Échec des connexions sortantes inspectées par TLS avec SSLV3_ALERT_HANDSHAKE_FAILURE ou RemoteDisconnected

Les requêtes sortantes de votre agent échouent lors de la première connexion à un hôte de destination avec SSLV3_ALERT_HANDSHAKE_FAILURE, ou échouent avec RemoteDisconnected.

Lors de la première connexion inspectée par TLS à un hôte de destination, Secure Web Proxy crée et met en cache un certificat d'entité finale à partir de Certificate Authority Service, ce qui peut provoquer une erreur de handshake temporaire. Les clients HTTP qui envoient Connection: close par défaut, tels que urllib.request.urlopen, peuvent échouer avec RemoteDisconnected lors de l'interception TLS.

Pour éviter ces erreurs dans le code de votre agent :

  • Utilisez des clients HTTP qui réutilisent les connexions persistantes, tels que httpx.AsyncClient ou requests.Session().
  • Configurez les nouvelles tentatives de connexion et de handshake sur votre client HTTP, tel que httpx.AsyncHTTPTransport(retries=2) ou urllib3.util.Retry.

Étapes suivantes