如果 Cloud Run 代理的傳出要求失敗或略過 Agent Gateway,請使用下列檢查追蹤要求路徑,或參閱「常見問題和解決方法」。如需設定操作說明,請參閱「使用 Agent Gateway 控管代理」。
流量抵達 Agent Gateway 前,Cloud Run Envoy sidecar 會從 Traffic Director API 擷取轉送和憑證設定。sidecar 會透過 mTLS CONNECT 通道,將傳出流量傳送至 Secure Web Proxy。
在 Envoy sidecar 存取記錄中驗證傳出轉送
Cloud Run Envoy sidecar 攔截傳出 TCP 連線時,會將 JSON 存取記錄項目寫入 run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log,並包含 jsonPayload.upstream_host 欄位。
從 Cloud Run 服務觸發傳出要求,並查詢 sidecar 存取記錄:
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 sidecar xDS 和連線記錄」。
查看 Envoy sidecar 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-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)"
更改下列內容:
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 sidecar 將流量轉送至 Secure Web Proxy,但要求失敗,請按照「查看 Proxy 交易記錄」一文所述,檢查 Proxy 記錄:
- 如果 Proxy 記錄中未顯示任何流量,表示要求未到達 Secure Web Proxy。請參閱「稽核 EgressRouting 和 AgentGateway 資源 URI」和「常見問題和解決方法」,檢查
EgressRouting設定。 - 如果發現非預期的
DENY或ALLOW決策,請檢查記錄項目中的jsonPayload.authzPolicyInfo和jsonPayload.agentGatewayInfo,查看相符的AuthzPolicy和目的地中繼資料,並驗證附加至 Agent Gateway 資源的所有ExtensionBinding規則。建立或更新ExtensionBinding資源後,設定變更最多可能需要五分鐘才會套用至閘道。
常見問題和解決方法
以下各節說明常見問題和解決方法。
資源 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 服務代理可以存取虛擬私有雲網路。根據預設,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 建立通道
更新現有 Secure Web Proxy 閘道的 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 會透過安全網路 Proxy 轉送所有傳出容器流量,因此要求會因下列其中一項原因而失敗:
- 您的 Identity-Aware Proxy (IAP)
ExtensionBinding略過matchConditions(或比對 Model Context Protocol (MCP) 伺服器以外的主機),但 Identity and Access Management (IAM) 統一存取權政策中沒有目的地允許規則。 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
您在 Secure Web Proxy Gateway 上建立了 GatewaySecurityPolicyRule 資源,但這些資源不會影響傳出代理流量。
Secure Web Proxy 與 AgentGateway 資源建立關聯後,會忽略基礎 Gateway 上的所有 GatewaySecurityPolicyRule 資源 (其 TlsInspectionPolicy 仍會保持啟用狀態)。
請改為將 ExtensionBinding 資源附加至 Agent Gateway 資源。如果使用 AuthzPolicy 資源,請僅將其附加至 Agent Gateway 資源;如果將 AuthzPolicy 資源同時附加至 AgentGateway 和基礎 Secure Web Proxy Gateway,會導致設定衝突。如需操作說明,請參閱「在 Agent Gateway 設定政策」。
傳出要求未通過 TLS 檢查
Cloud Run 代理程式的傳出要求失敗,每次連線都發生 TLS 錯誤。
Secure Web Proxy 服務帳戶缺少憑證授權單位服務集區的 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 服務建立並快取分葉憑證,這可能會導致暫時性握手錯誤。預設傳送 Connection: close 的 HTTP 用戶端 (例如 urllib.request.urlopen),在 TLS 攔截期間可能會失敗,並顯示 RemoteDisconnected。
如要避免在代理程式碼中發生這些錯誤,請按照下列步驟操作:
- 使用可重複使用永久連線的 HTTP 用戶端,例如
httpx.AsyncClient或requests.Session()。 - 在 HTTP 用戶端 (例如
httpx.AsyncHTTPTransport(retries=2)或urllib3.util.Retry) 設定連線和握手重試。