Cuando una solicitud saliente de tu agente de Cloud Run falla o omite Agent Gateway, sigue la ruta de la solicitud con las siguientes verificaciones o consulta Problemas comunes y soluciones. Para obtener instrucciones de configuración, consulta Administra agentes con Agent Gateway.
Antes de que el tráfico llegue a Agent Gateway, el
sidecar de Envoy de Cloud Run recupera la configuración de enrutamiento y certificados
de la API de Traffic Director. El sidecar envía tráfico saliente a través de
un túnel mTLS CONNECT al Secure Web Proxy.
Verifica el enrutamiento de salida en los registros de acceso del sidecar de Envoy
Cuando el archivo adicional de Envoy de Cloud Run intercepta una conexión TCP
saliente, escribe una entrada de registro de acceso JSON en
run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log con el
campo jsonPayload.upstream_host.
Activa una solicitud saliente desde tu servicio de Cloud Run y consulta los registros de acceso del archivo adicional:
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)"
Reemplaza lo siguiente:
SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run.PROJECT_ID: Es el ID del proyecto de Google Cloud .
Una conexión en buen estado a través de la puerta de enlace devuelve un resultado similar al siguiente:
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
Verifica los valores de UPSTREAM_HOST y RESPONSE_FLAGS:
- Si
UPSTREAM_HOSTesenvoy://tunnel_internal_listener/yRESPONSE_FLAGSes-, la conexión está en buen estado. El sidecar de Envoy coincidió con tu política deEgressRoutingy reenvió la conexión a Agent Gateway. - Si
UPSTREAM_HOSTes una dirección IP y un puerto de destino, como93.184.216.34:443, la API de Traffic Director no pudo coincidir con tu política deEgressRoutingni resolver la puerta de enlace de destino. Envoy usó el paso deORIGINAL_DSTy omitió Agent Gateway. Consulta Audita los URIs de recursos de EgressRouting y AgentGateway. - Si
UPSTREAM_HOSTesenvoy://tunnel_internal_listener/yRESPONSE_FLAGSesUFoUH, oBYTES_RECEIVEDes0, Envoy no pudo abrir el túnelCONNECTa Secure Web Proxy. Verifica la conectividad de la subred de la nube privada virtual (VPC) o consulta La actualización de la puerta de enlace de Secure Web Proxy interrumpe la tunelización de Envoy. - Si no aparece ninguna fila, verifica
run.googleapis.com%2Frequestspara confirmar que la solicitud llegó a tu contenedor de Cloud Run. Verifica que tu revisión activa habilite--ambient-networking. Si las filas aún no aparecen, consulta Verifica los registros de conexión y xDS del archivo adicional de Envoy.
Verifica los registros de conexión y xDS del archivo adicional de Envoy
Si los registros de acceso del sidecar de Envoy no devuelven entradas o muestran una falla de conexión, inspecciona los registros de conexión de xDS y upstream del sidecar:
Verifica si hay errores de transmisión de xDS de la API de Traffic Director o el estado de inicio:
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)"
Verifica los intentos de conexión del túnel ascendente a
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)"
Reemplaza lo siguiente:
SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run.PROJECT_ID: Es el ID del proyecto de Google Cloud .
Verifica los mensajes de registro:
- Si los registros contienen
DeltaAggregatedResources gRPC config streamyThe caller does not have permission, a la identidad del servicio le faltaroles/trafficdirector.client. Consulta El archivo adicional de Envoy no puede recibir la configuración de xDS. - Si los registros contienen
Creating connection to cluster ambient-swp-connect-cluster, Envoy recibió la configuración deEgressRoutingy trató de conectarse a Secure Web Proxy.
Audita los URIs de recursos de EgressRouting y AgentGateway
Cuando ejecutas gcloud alpha network-services egress-routings create o
gcloud beta network-services agent-gateways import, la API valida la sintaxis
del URI sin verificar si existen los recursos objetivo. Un error tipográfico en un
nombre de recurso o región hace que la API de Traffic Director omita la traducción de EgressRouting,
y Envoy usa el enrutamiento de transferencia.
Inspecciona los URI almacenados y compáralos con tus recursos implementados:
Inspecciona el recurso
EgressRouting. En el resultado, se normalizan los IDs de los proyectos en números de proyectos:gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \ --location=REGION \ --project=PROJECT_ID
Enumera todos los recursos
EgressRoutingde la región para confirmar que ninguna política duplicada se oriente al mismo servicio:gcloud alpha network-services egress-routings list \ --location=REGION \ --project=PROJECT_ID
Verifica que la puerta de enlace de Secure Web Proxy de destino coincida con el URI en
EgressRouting.gatewayyAgentGateway.selfManaged.resourceUris:gcloud network-services gateways describe SWP_NAME \ --location=REGION \ --project=PROJECT_ID
Reemplaza lo siguiente:
EGRESS_ROUTING_NAME: Es el nombre de tu recursoEgressRouting.REGION: Es la región de tu implementación.PROJECT_ID: Es el ID del proyecto de Google Cloud .SWP_NAME: Es el nombre de tu puerta de enlace de Secure Web Proxy.
Verifica que los tres URIs coincidan con el ID del proyecto o número, la región y el nombre del recurso:
EgressRouting.sources[].workloadUri:- Permisos con alcance de servicio:
//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME - Con alcance de proyecto:
//run.googleapis.com/projects/PROJECT_IDo//run.googleapis.com/projects/PROJECT_NUMBER
- Permisos con alcance de servicio:
EgressRouting.gateway://networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAMEAgentGateway.selfManaged.resourceUris[]:projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME
Verifica los registros de transacciones de Secure Web Proxy
Si el sidecar de Envoy reenvía el tráfico a Secure Web Proxy, pero las solicitudes fallan, inspecciona los registros del proxy como se describe en Visualiza los registros de transacciones del proxy:
- Si no aparece tráfico en los registros del proxy, las solicitudes no llegan a Secure Web Proxy. Verifica la configuración de
EgressRoutingen Audita los URI de recursos de EgressRouting y AgentGateway y Problemas y soluciones habituales. - Si ves decisiones
DENYoALLOWinesperadas, verificajsonPayload.authzPolicyInfoyjsonPayload.agentGatewayInfoen la entrada de registro para inspeccionar los metadatos de destino yAuthzPolicycoincidentes, y verifica las reglas deExtensionBindingadjuntas a tu recurso de Agent Gateway. Después de crear o actualizar un recursoExtensionBinding, los cambios de configuración pueden tardar hasta cinco minutos en propagarse a la puerta de enlace.
Problemas comunes y soluciones
En las siguientes secciones, se describen los problemas habituales y cómo resolverlos.
El tráfico saliente omite Agent Gateway debido a un URI de recurso que no coincide
El tráfico saliente de Cloud Run omite
Agent Gateway o se agota el tiempo de espera después de que se realiza correctamente
egress-routings create. En envoy_sidecar_log, jsonPayload.upstream_host muestra la
dirección IP y el puerto de destino en lugar de envoy://tunnel_internal_listener/.
Uno de los URI de recursos EgressRouting o AgentGateway hace referencia a un
nombre de recurso inexistente o a una región que no coincide. Cuando la API de Traffic Director
no puede resolver la cadena desde el servicio de Cloud Run hasta
Secure Web Proxy, omite la traducción del túnel y entrega ORIGINAL_DST.
Ejecuta los comandos en
Audita los URI de recursos de EgressRouting y AgentGateway para
encontrar el URI que no coincide. Actualiza la configuración con el nombre y la región del recurso
coincidentes, y vuelve a crear el recurso AgentGateway o EgressRouting.
El sidecar de Envoy no puede recibir la configuración de xDS
Las solicitudes salientes del contenedor de Cloud Run agotan el tiempo de espera o fallan,
y envoy_sidecar_log contiene el siguiente error:
DeltaAggregatedResources gRPC config stream to trafficdirector.REGION.rep.googleapis.com:443 closed: 7, The caller does not have permission
La identidad del servicio del entorno de ejecución de Cloud Run no tiene
roles/trafficdirector.client. De forma predeterminada, implementar un servicio con
--functional-type=agent y --identity-type=agent-identity otorga
roles/run.agentDefaultAccess, que incluye roles/trafficdirector.client
y roles/cloudtrace.agent. Si a tu identidad de servicio le faltan estos
permisos, otorga los roles:
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"
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto de Google Cloud .ORGANIZATION_ID: Es el ID de la organización de Google Cloud .PROJECT_NUMBER: Es el número del proyecto de Google Cloud .REGION: Es la región de tu servicio.SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run. Si tu servicio usa una cuenta de servicio en lugar de la identidad del agente, establece--memberenserviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.
Confirma que el agente de servicio de Cloud Run pueda acceder a tu
red de VPC. De forma predeterminada, roles/run.serviceAgent incluye estos
permisos. Si modificaste los permisos del agente de servicio, otorga
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 actualización de la puerta de enlace de Secure Web Proxy interrumpe la tunelización de Envoy
Después de actualizar el ServerTlsPolicy, el certificado, la dirección IP o el puerto de una puerta de enlace de Secure Web Proxy existente, las solicitudes salientes fallan con errores 502, 503 o 504, o envoy_sidecar_log informa RESPONSE_FLAGS: UF.
No puedes cambiar addresses ni ports después de crear una puerta de enlace de Secure Web Proxy. Además, las actualizaciones de serverTlsPolicy o certificateUrls en una
puerta de enlace de Secure Web Proxy existente no se propagan a los extremos de EgressRouting
en la API de Traffic Director.
Para cambiar estos campos de Secure Web Proxy sin tiempo de inactividad de la carga de trabajo, completa los siguientes pasos:
- Crea una puerta de enlace de Secure Web Proxy de reemplazo con un nombre de recurso diferente y la configuración actualizada.
- Actualiza
selfManaged.resourceUrisen el recursoAgentGatewaypara hacer referencia al URI de la puerta de enlace de Secure Web Proxy de reemplazo. - Vuelve a crear tu recurso
EgressRoutingpara que apunte a la puerta de enlace de Secure Web Proxy de reemplazo. - Después de que la puerta de enlace de reemplazo enrute el tráfico, quita la puerta de enlace de Secure Web Proxy
antigua del recurso
AgentGatewayy bórrala.
Las solicitudes salientes fallan con errores 403
Las solicitudes salientes de tu agente de Cloud Run, incluidas las llamadas a
los extremos del modelo, como Vertex AI en
REGION-aiplatform.googleapis.com o
aiplatform.googleapis.com, fallan con errores 403 Forbidden después de
configurar las políticas en Agent Gateway.
Debido a que --vpc-egress=all enruta todo el tráfico saliente del contenedor a través de
Secure Web Proxy, las solicitudes fallan por uno de los siguientes motivos:
- Tu Identity-Aware Proxy (IAP)
ExtensionBindingomitematchConditions(o coincide con hosts fuera de los servidores del protocolo de contexto del modelo [MCP]) sin una regla de permiso para el destino en tu política de acceso unificado de Identity and Access Management (IAM). - Se adjunta una
ALLOWAuthzPolicya tu recurso de Agent Gateway (o al Secure Web ProxyGatewaysubyacente), y las solicitudes salientes no coinciden con sus reglas deALLOW.
Para solucionar este problema, sigue estos pasos:
- Limita el alcance de
matchConditionsen tuExtensionBindingde IAP aprefix: "urn:mcp"para los servidores de MCP (y, de forma opcional,prefix: "urn:agent"para el tráfico de agente a agente) de modo que las llamadas de modelos y otros destinos que no sean de MCP omitan la evaluación de IAP, o bien agrega una regla de permisodestination.unregistered.hostpara tu destino (comoREGION-aiplatform.googleapis.comoaiplatform.googleapis.com) en tu política de acceso unificado de IAM. Para obtener instrucciones, consulta Configura políticas de salida de IAP. - Si adjuntaste un
AuthzPolicydeALLOW, agrega reglas deALLOWpara tus destinos obligatorios o quita elAuthzPolicysi controlas el tráfico solo con recursos deExtensionBinding.
Secure Web Proxy ignora las GatewaySecurityPolicyRules
Creaste recursos GatewaySecurityPolicyRule en el Secure Web Proxy
Gateway, pero no tienen efecto en el tráfico saliente del agente.
Cuando Secure Web Proxy se asocia con un recurso AgentGateway, Secure Web Proxy ignora todos los recursos GatewaySecurityPolicyRule en la Gateway subyacente (su TlsInspectionPolicy permanece activa).
En su lugar, adjunta recursos ExtensionBinding a tu recurso de Agent Gateway. Si usas recursos AuthzPolicy, adjúntalos solo a tu
recurso de Agent Gateway. Si adjuntas recursos AuthzPolicy
tanto a AgentGateway como al Secure Web Proxy Gateway subyacente, se produce
un conflicto de configuración. Para obtener instrucciones, consulta
Configura políticas en Agent Gateway.
Las solicitudes de salida fallan en la inspección de TLS
Las solicitudes salientes de tu agente de Cloud Run fallan con errores de TLS en cada conexión.
A la cuenta de servicio de Secure Web Proxy le falta
roles/privateca.certificateManager en tu grupo de Certificate Authority Service.
Otorga roles/privateca.certificateManager en el grupo de AC a tu
cuenta de servicio de Secure Web Proxy. Para obtener instrucciones, consulta
Crea una cuenta de servicio.
Las conexiones salientes con inspección de TLS fallan con SSLV3_ALERT_HANDSHAKE_FAILURE o RemoteDisconnected
Las solicitudes salientes de tu agente fallan en la primera conexión a un host de destino
con SSLV3_ALERT_HANDSHAKE_FAILURE o con RemoteDisconnected.
En la primera conexión con inspección de TLS a un host de destino, Secure Web Proxy
crea y almacena en caché un certificado de hoja del Servicio de CA, lo que puede
provocar un error de protocolo de enlace transitorio. Los clientes HTTP que envían Connection: close de forma
predeterminada, como urllib.request.urlopen, pueden fallar con RemoteDisconnected
durante la intercepción de TLS.
Para evitar estos errores en el código de tu agente, haz lo siguiente:
- Usa clientes HTTP que reutilicen conexiones persistentes, como
httpx.AsyncClientorequests.Session(). - Configura los reintentos de conexión y de protocolo de enlace en tu cliente HTTP, como
httpx.AsyncHTTPTransport(retries=2)ourllib3.util.Retry.
¿Qué sigue?
- Administra agentes con Agent Gateway
- Configura Ambient Networking para Cloud Run
- Soluciona problemas de Cloud Run