排解 Agent Gateway 問題

如果 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 和上游連線記錄:

  1. 檢查 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)"
  2. 檢查上游通道連線嘗試連至 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,並與已部署的資源進行比較:

  1. 檢查 EgressRouting 資源。輸出內容會將專案 ID 標準化為專案編號:

    gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \
       --location=REGION \
       --project=PROJECT_ID
  2. 列出區域中的所有 EgressRouting 資源,確認沒有重複的政策指定相同服務:

    gcloud alpha network-services egress-routings list \
       --location=REGION \
       --project=PROJECT_ID
  3. 確認目標 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_NAME
  • AgentGateway.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 欄位,且不中斷工作負載,請完成下列步驟:

  1. 使用不同的資源名稱和更新後的設定,建立替代的 Secure Web Proxy 閘道。
  2. 更新 AgentGateway 資源中的 selfManaged.resourceUris,參照替換的 Secure Web Proxy 閘道 URI。
  3. 重新建立 EgressRouting 資源,指向替代的 Secure Web Proxy 閘道。
  4. 替換閘道轉送流量後,請從 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) 統一存取權政策中沒有目的地允許規則。
  • ALLOW AuthzPolicy 已附加至 Agent Gateway 資源 (或基礎 Secure Web Proxy Gateway),且傳出要求不符合其 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 輸出政策」。
  • 如果您附加了 ALLOW AuthzPolicy,請為必要目的地新增 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) 設定連線和握手重試。

後續步驟