如果 Cloud Run 智能体的出站请求失败或绕过 Agent Gateway,请使用以下检查来跟踪请求路径,或参阅常见问题和解决方法。如需查看设置说明,请参阅使用 Agent Gateway 治理智能体。
在流量到达 Agent Gateway 之前,Cloud Run Envoy Sidecar 会从 Traffic Director API 提取路由和证书配置。边车通过 mTLS CONNECT 隧道将出站流量发送到 Secure Web Proxy。
在 Envoy Sidecar 访问日志中验证出站路由
当 Cloud Run Envoy 边车拦截出站 TCP 连接时,它会使用 jsonPayload.upstream_host 字段将 JSON 访问日志条目写入 run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log。
从 Cloud Run 服务触发一个出站请求,并查询边车访问日志:
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)"
替换以下内容:
SERVICE_NAME:Cloud Run 代理服务的名称。PROJECT_ID:您的 Google Cloud 项目 ID。
通过网关建立的健康连接会返回类似于以下内容的输出:
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
检查 UPSTREAM_HOST 和 RESPONSE_FLAGS 值:
- 如果
UPSTREAM_HOST为envoy://tunnel_internal_listener/且RESPONSE_FLAGS为-,则连接运行状况良好。Envoy sidecar 与您的EgressRouting政策匹配,并将连接转发到 Agent Gateway。 - 如果
UPSTREAM_HOST是目标 IP 地址和端口(例如93.184.216.34:443),则 Traffic Director API 无法匹配您的EgressRouting政策或解析目标网关。Envoy 使用了ORIGINAL_DST直通,并绕过了 Agent Gateway。请参阅审核 EgressRouting 和 AgentGateway 资源 URI。 - 如果
UPSTREAM_HOST为envoy://tunnel_internal_listener/且RESPONSE_FLAGS为UF或UH,或者BYTES_RECEIVED为0,则 Envoy 无法打开通往 Secure Web Proxy 的CONNECT隧道。检查您的虚拟私有云 (VPC) 子网连接,或参阅更新 Secure Web Proxy 网关会破坏 Envoy 隧道。 - 如果未显示任何行,请检查
run.googleapis.com%2Frequests,确认请求已到达 Cloud Run 容器。验证您的活跃修订版本是否启用了--ambient-networking。如果行仍未显示,请参阅检查 Envoy 边车 xDS 和连接日志。
检查 Envoy 边车 xDS 和连接日志
如果 Envoy sidecar 访问日志未返回任何条目或显示连接失败,请检查 sidecar xDS 和上游连接日志:
检查 Traffic Director API xDS 流错误或启动状态:
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)"
检查上游隧道连接尝试:
ambient-swp-connect-clustergcloud 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)"
替换以下内容:
SERVICE_NAME:Cloud Run 代理服务的名称。PROJECT_ID:您的 Google Cloud 项目 ID。
查看日志消息:
- 如果日志包含
DeltaAggregatedResources gRPC config stream和The caller does not have permission,则服务身份缺少roles/trafficdirector.client。请参阅 Envoy Sidecar 无法接收 xDS 配置。 - 如果日志包含
Creating connection to cluster ambient-swp-connect-cluster,则表示 Envoy 收到了EgressRouting配置并尝试连接到 Secure Web Proxy。
审核 EgressRouting 和 AgentGateway 资源 URI
当您运行 gcloud alpha network-services egress-routings create 或 gcloud beta network-services agent-gateways import 时,API 会验证 URI 语法,而不会检查目标资源是否存在。资源名称或区域中的拼写错误会导致 Traffic Director API 跳过 EgressRouting 转换,并且 Envoy 会使用直通路由。
检查存储的 URI,并将其与已部署的资源进行比较:
检查
EgressRouting资源。输出会将项目 ID 规范化为项目编号:gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \ --location=REGION \ --project=PROJECT_ID
列出该区域中的所有
EgressRouting资源,以确认没有重复的政策定位到同一服务:gcloud alpha network-services egress-routings list \ --location=REGION \ --project=PROJECT_ID
验证目标 Secure Web Proxy 网关是否与
EgressRouting.gateway和AgentGateway.selfManaged.resourceUris中的 URI 匹配:gcloud network-services gateways describe SWP_NAME \ --location=REGION \ --project=PROJECT_ID
替换以下内容:
EGRESS_ROUTING_NAME:您的EgressRouting资源的名称。REGION:部署所在的区域。PROJECT_ID:您的 Google Cloud 项目 ID。SWP_NAME:Secure Web Proxy 网关的名称。
验证这三个 URI 是否都与您的项目 ID 或编号、区域和资源名称匹配:
EgressRouting.sources[].workloadUri:- 服务级:
//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME - 项目级:
//run.googleapis.com/projects/PROJECT_ID或//run.googleapis.com/projects/PROJECT_NUMBER
- 服务级:
EgressRouting.gateway://networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAMEAgentGateway.selfManaged.resourceUris[]:projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME
查看 Secure Web Proxy 事务日志
如果 Envoy 边车将流量转发到 Secure Web Proxy,但请求失败,请按照查看代理事务日志中的说明检查代理日志:
- 如果代理日志中未显示任何流量,则表示请求未到达 Secure Web Proxy。在审核 EgressRouting 和 AgentGateway 资源 URI 以及常见问题和解决方法中检查您的
EgressRouting配置。 - 如果您看到意外的
DENY或ALLOW决策,请检查日志条目中的jsonPayload.authzPolicyInfo和jsonPayload.agentGatewayInfo,以检查匹配的AuthzPolicy和目标元数据,并验证附加到 Agent Gateway 资源的任何ExtensionBinding规则。创建或更新ExtensionBinding资源后,配置更改最多可能需要 5 分钟才能传播到网关。
常见问题和解决方法
以下部分介绍了常见问题以及解决方法。
由于资源 URI 不匹配,出站流量绕过了 Agent Gateway
来自 Cloud Run 的出站流量会绕过 Agent Gateway,或在 egress-routings create 成功后超时。在 envoy_sidecar_log 中,jsonPayload.upstream_host 显示目标 IP 地址和端口,而不是 envoy://tunnel_internal_listener/。
EgressRouting 或 AgentGateway 资源 URI 之一引用了不存在的资源名称或不匹配的区域。当 Traffic Director API 无法解析从 Cloud Run 服务到 Secure Web Proxy 的链时,它会跳过隧道转换并提供 ORIGINAL_DST。
运行审核 EgressRouting 和 AgentGateway 资源 URI 中的命令,找到不匹配的 URI。使用匹配的资源名称和区域更新配置,然后重新创建 AgentGateway 或 EgressRouting 资源。
Envoy sidecar 无法接收 xDS 配置
来自 Cloud Run 容器的出站请求超时或失败,并且 envoy_sidecar_log 包含以下错误:
DeltaAggregatedResources gRPC config stream to trafficdirector.REGION.rep.googleapis.com:443 closed: 7, The caller does not have permission
Cloud Run 运行时服务身份没有 roles/trafficdirector.client。默认情况下,使用 --functional-type=agent 和 --identity-type=agent-identity 部署服务会授予 roles/run.agentDefaultAccess,其中包括 roles/trafficdirector.client 和 roles/cloudtrace.agent。如果您的服务身份缺少这些权限,请授予以下角色:
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"
替换以下内容:
PROJECT_ID:您的 Google Cloud 项目 ID。ORGANIZATION_ID:您的 Google Cloud 组织 ID。PROJECT_NUMBER:您的 Google Cloud 项目编号。REGION:服务所在的区域。SERVICE_NAME:Cloud Run 代理服务的名称。如果您的服务使用服务账号而不是代理身份,请将--member设置为serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com。
确认 Cloud Run 服务代理可以访问您的 VPC 网络。默认情况下,roles/run.serviceAgent 包含这些权限。如果您修改了服务代理权限,请授予 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"
更新 Secure Web Proxy 网关会破坏 Envoy 隧道
更新现有安全 Web 代理网关的 ServerTlsPolicy、证书、IP 地址或端口后,出站请求失败,并显示 502、503 或 504 错误,或者 envoy_sidecar_log 报告 RESPONSE_FLAGS: UF。
创建 Secure Web Proxy 网关后,您无法更改 addresses 或 ports。此外,对现有 Secure Web Proxy 网关上的 serverTlsPolicy 或 certificateUrls 的更新不会传播到 Traffic Director API 中的 EgressRouting 端点。
如需在不造成工作负载停机的情况下更改这些 Secure Web Proxy 字段,请完成以下步骤:
- 使用其他资源名称和更新后的配置创建替换 Secure Web Proxy 网关。
- 更新
AgentGateway资源中的selfManaged.resourceUris,以引用替换 Secure Web Proxy 网关 URI。 - 重新创建
EgressRouting资源,以指向替换 Secure Web Proxy 网关。 - 在替换网关路由流量后,从
AgentGateway资源中移除旧的 Secure Web Proxy 网关,并删除旧的 Secure Web Proxy 网关。
出站请求失败并显示 403 错误
在 Agent Gateway 上配置政策后,来自 Cloud Run 智能体的出站请求(包括对 REGION-aiplatform.googleapis.com 或 aiplatform.googleapis.com 处的 Vertex AI 等模型端点的调用)会失败,并显示 403 Forbidden 错误。
由于 --vpc-egress=all 会通过 Secure Web Proxy 路由所有出站容器流量,因此请求会因以下原因之一而失败:
- 您的 Identity-Aware Proxy (IAP)
ExtensionBinding省略了matchConditions(或匹配 Model Context Protocol [MCP] 服务器之外的主机),且您的 Identity and Access Management [IAM] Unified Access Policy 中没有针对该目标的允许规则。 ALLOWAuthzPolicy附加到您的 Agent Gateway 资源(或底层 Secure Web ProxyGateway),并且出站请求与其ALLOW规则不匹配。
要解决此问题,请执行以下操作:
- 将 IAP
ExtensionBinding中的matchConditions范围限定为 MCP 服务器的prefix: "urn:mcp"(以及可选的代理间流量的prefix: "urn:agent"),以便模型调用和其他非 MCP 目标绕过 IAP 评估,或者在 IAM 统一访问权限政策中为目标(例如REGION-aiplatform.googleapis.com或aiplatform.googleapis.com)添加destination.unregistered.host允许规则。如需了解相关说明,请参阅配置 IAP 出站流量政策。 - 如果您附加了
ALLOWAuthzPolicy,请为所需目标添加ALLOW规则;如果您仅使用ExtensionBinding资源管理流量,请移除AuthzPolicy。
Secure Web Proxy 会忽略 GatewaySecurityPolicyRules
您在安全 Web 代理 Gateway 上创建了 GatewaySecurityPolicyRule 资源,但这些资源对出站代理流量没有影响。
当 Secure Web Proxy 与 AgentGateway 资源关联时,Secure Web Proxy 会忽略底层 Gateway 上的所有 GatewaySecurityPolicyRule 资源(其 TlsInspectionPolicy 仍处于活跃状态)。
改为将 ExtensionBinding 资源附加到 Agent Gateway 资源。如果您使用 AuthzPolicy 资源,请仅将其附加到 Agent Gateway 资源;将 AuthzPolicy 资源同时附加到 AgentGateway 和底层 Secure Web Proxy Gateway 会导致配置冲突。如需查看相关说明,请参阅在 Agent Gateway 上配置政策。
出站请求未通过 TLS 检查
来自 Cloud Run 代理的出站请求在每次连接时都会失败,并显示 TLS 错误。
Secure Web Proxy 服务账号在 Certificate Authority Service 池中缺少 roles/privateca.certificateManager。
将 CA 池的 roles/privateca.certificateManager 授予您的 Secure Web Proxy 服务账号。如需查看相关说明,请参阅创建服务账号。
经过 TLS 检查的出站连接失败,并显示 SSLV3_ALERT_HANDSHAKE_FAILURE 或 RemoteDisconnected
代理发出的出站请求在首次连接到目标主机时失败,并显示 SSLV3_ALERT_HANDSHAKE_FAILURE,或失败并显示 RemoteDisconnected。
在与目标主机的第一个 TLS 检查连接中,Secure Web Proxy 会从 CA Service 铸造并缓存叶证书,这可能会导致暂时性握手错误。默认发送 Connection: close 的 HTTP 客户端(例如 urllib.request.urlopen)在 TLS 拦截期间可能会失败,并显示 RemoteDisconnected。
为防止在代理代码中出现这些错误,请执行以下操作:
- 使用可重复使用持久连接的 HTTP 客户端,例如
httpx.AsyncClient或requests.Session()。 - 在 HTTP 客户端(例如
httpx.AsyncHTTPTransport(retries=2)或urllib3.util.Retry)上配置连接和握手重试。