Memecahkan masalah Agent Gateway

Pratinjau Terbatas untuk Agent Gateway di Cloud Run

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Fitur ini dalam Pratinjau terbatas dan hanya tersedia untuk project dalam daftar yang diizinkan. Untuk meminta akses awal, daftar di sini untuk mendapatkan pratinjau.

Jika permintaan keluar dari agen Cloud Run Anda gagal atau melewati Gateway Agen, lacak jalur permintaan menggunakan pemeriksaan berikut atau lihat Masalah umum dan solusinya. Untuk mengetahui petunjuk penyiapan, lihat Mengelola agen dengan Agent Gateway.

Sebelum traffic mencapai Agent Gateway, sidecar Envoy Cloud Run mengambil konfigurasi pemilihan rute dan sertifikat dari Traffic Director API. Sidecar mengirimkan traffic keluar melalui tunnel CONNECT mTLS ke Secure Web Proxy.

Memverifikasi pemilihan rute keluar di log akses sidecar Envoy

Saat sidecar Envoy Cloud Run menangkap koneksi TCP keluar, sidecar tersebut akan menulis entri log akses JSON ke run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log dengan kolom jsonPayload.upstream_host.

Picu permintaan keluar dari layanan Cloud Run Anda dan buat kueri log akses 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)"

Ganti kode berikut:

• SERVICE_NAME: nama layanan agen Cloud Run Anda.
• PROJECT_ID: Project ID Google Cloud Anda.

Koneksi yang responsif melalui gateway akan menampilkan output yang mirip dengan berikut ini:

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

Periksa nilai UPSTREAM_HOST dan RESPONSE_FLAGS:

• Jika UPSTREAM_HOST adalah envoy://tunnel_internal_listener/ dan RESPONSE_FLAGS adalah -, koneksi responsif. Sidecar Envoy cocok dengan kebijakan EgressRouting Anda dan meneruskan koneksi ke Agent Gateway.
• Jika UPSTREAM_HOST adalah alamat IP dan port tujuan seperti 93.184.216.34:443, Traffic Director API tidak dapat mencocokkan kebijakan EgressRouting Anda atau me-resolve gateway target. Envoy menggunakan passthrough ORIGINAL_DST dan mengabaikan Agent Gateway. Lihat Mengaudit URI resource EgressRouting dan AgentGateway.
• Jika UPSTREAM_HOST adalah envoy://tunnel_internal_listener/ dan RESPONSE_FLAGS adalah UF atau UH, atau BYTES_RECEIVED adalah 0, Envoy tidak dapat membuka tunnel CONNECT ke Secure Web Proxy. Periksa konektivitas subnet Virtual Private Cloud (VPC) Anda atau lihat Memperbarui gateway Secure Web Proxy akan merusak tunneling Envoy.
• Jika tidak ada baris yang muncul, periksa run.googleapis.com%2Frequests untuk mengonfirmasi bahwa permintaan telah mencapai container Cloud Run Anda. Pastikan revisi aktif Anda mengaktifkan --ambient-networking. Jika baris masih tidak muncul, lihat Memeriksa xDS sidecar Envoy dan log koneksi.

Memeriksa xDS sidecar Envoy dan log koneksi

Jika log akses sidecar Envoy tidak menampilkan entri atau menunjukkan kegagalan koneksi, periksa log koneksi upstream dan xDS sidecar:

1. Periksa error streaming xDS Traffic Director API atau status startup:

   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. Periksa upaya koneksi tunnel upstream ke 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)"

   Ganti kode berikut:

   • SERVICE_NAME: nama layanan agen Cloud Run Anda.
   • PROJECT_ID: Project ID Google Cloud Anda.

Periksa pesan log:

• Jika log berisi DeltaAggregatedResources gRPC config stream dan The caller does not have permission, identitas layanan tidak memiliki roles/trafficdirector.client. Lihat Sidecar Envoy tidak dapat menerima konfigurasi xDS.
• Jika log berisi Creating connection to cluster ambient-swp-connect-cluster, Envoy menerima konfigurasi EgressRouting dan mencoba terhubung ke Secure Web Proxy.

Mengaudit URI resource EgressRouting dan AgentGateway

Saat Anda menjalankan gcloud alpha network-services egress-routings create atau gcloud beta network-services agent-gateways import, API akan memvalidasi sintaksis URI tanpa memeriksa apakah resource target ada. Kesalahan ketik pada nama resource atau region menyebabkan Traffic Director API melewati penerjemahan EgressRouting, dan Envoy menggunakan pemilihan rute passthrough.

Periksa URI yang disimpan dan bandingkan dengan resource yang di-deploy:

1. Periksa resource EgressRouting. Output akan menormalisasi project ID menjadi nomor project:

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

2. Cantumkan semua resource EgressRouting di region untuk mengonfirmasi bahwa tidak ada kebijakan duplikat yang menargetkan layanan yang sama:

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

3. Pastikan gateway Secure Web Proxy target cocok dengan URI di EgressRouting.gateway dan AgentGateway.selfManaged.resourceUris:

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

   Ganti kode berikut:

   • EGRESS_ROUTING_NAME: nama resource EgressRouting.
   • REGION: region deployment Anda.
   • PROJECT_ID: Project ID Google Cloud Anda.
   • SWP_NAME: nama gateway Secure Web Proxy Anda.

Pastikan ketiga URI cocok dengan project ID atau nomor, region, dan nama resource Anda:

• EgressRouting.sources[].workloadUri:
  • Cakupan layanan: //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
  • Cakupan project: //run.googleapis.com/projects/PROJECT_ID atau //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

Memeriksa log transaksi Secure Web Proxy

Jika sidecar Envoy meneruskan traffic ke Secure Web Proxy, tetapi permintaan gagal, periksa log proxy Anda seperti yang dijelaskan dalam Melihat log transaksi proxy:

• Jika tidak ada traffic yang muncul di log proxy, permintaan tidak akan mencapai Secure Web Proxy. Periksa konfigurasi EgressRouting Anda di Mengaudit URI resource EgressRouting dan AgentGateway dan Masalah umum dan solusinya.
• Jika Anda melihat keputusan DENY atau ALLOW yang tidak terduga, periksa jsonPayload.authzPolicyInfo dan jsonPayload.agentGatewayInfo dalam entri log untuk memeriksa AuthzPolicy dan metadata tujuan yang cocok, serta verifikasi aturan ExtensionBinding yang dilampirkan ke resource Agent Gateway Anda. Setelah Anda membuat atau memperbarui resource ExtensionBinding, perubahan konfigurasi dapat memerlukan waktu hingga lima menit untuk diterapkan ke gateway.

Masalah dan penyelesaian umum

Bagian berikut menjelaskan masalah umum dan cara mengatasinya.

Traffic keluar mengabaikan Agent Gateway karena URI resource yang tidak cocok

Traffic keluar dari Cloud Run mengabaikan Agent Gateway atau waktu habis setelah egress-routings create berhasil. Di envoy_sidecar_log, jsonPayload.upstream_host menampilkan alamat IP dan port tujuan, bukan envoy://tunnel_internal_listener/.

Salah satu URI resource EgressRouting atau AgentGateway mereferensikan nama resource yang tidak ada atau region yang tidak cocok. Jika Traffic Director API tidak dapat me-resolve rantai dari layanan Cloud Run ke Secure Web Proxy, API ini akan melewati terjemahan tunnel dan menyajikan ORIGINAL_DST.

Jalankan perintah di Mengaudit URI resource EgressRouting dan AgentGateway untuk menemukan URI yang tidak cocok. Perbarui konfigurasi dengan nama dan region resource yang cocok, lalu buat ulang resource AgentGateway atau EgressRouting.

Sidecar Envoy tidak dapat menerima konfigurasi xDS

Permintaan keluar dari container Cloud Run mengalami waktu tunggu habis atau gagal, dan envoy_sidecar_log berisi error berikut:

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

Identitas layanan runtime Cloud Run tidak memiliki roles/trafficdirector.client. Secara default, men-deploy layanan dengan --functional-type=agent dan --identity-type=agent-identity akan memberikan roles/run.agentDefaultAccess, yang mencakup roles/trafficdirector.client dan roles/cloudtrace.agent. Jika identitas layanan Anda tidak memiliki izin ini, berikan peran:

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"

Ganti kode berikut:

• PROJECT_ID: Project ID Google Cloud Anda.
• ORGANIZATION_ID: ID organisasi Google Cloud Anda.
• PROJECT_NUMBER: nomor project Google Cloud Anda.
• REGION: region layanan Anda.
• SERVICE_NAME: nama layanan agen Cloud Run Anda. Jika layanan Anda menggunakan akun layanan, bukan Identitas Agen, tetapkan --member ke serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

Pastikan agen layanan Cloud Run dapat mengakses jaringan VPC Anda. Secara default, roles/run.serviceAgent menyertakan izin ini. Jika Anda mengubah izin agen layanan, berikan roles/compute.networkUser:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:[e-mail]" \
    --role="roles/compute.networkUser"

Mengupdate gateway Secure Web Proxy akan merusak tunneling Envoy

Setelah Anda memperbarui ServerTlsPolicy, sertifikat, alamat IP, atau port gateway Secure Web Proxy yang ada, permintaan keluar akan gagal dengan error 502, 503, atau 504, atau envoy_sidecar_log melaporkan RESPONSE_FLAGS: UF.

Anda tidak dapat mengubah addresses atau ports setelah membuat gateway Secure Web Proxy. Selain itu, update pada serverTlsPolicy atau certificateUrls di gateway Secure Web Proxy yang ada tidak diterapkan ke endpoint EgressRouting di Traffic Director API.

Untuk mengubah kolom Secure Web Proxy ini tanpa periode nonaktif workload, selesaikan langkah-langkah berikut:

1. Buat gateway Secure Web Proxy pengganti dengan nama resource yang berbeda dan konfigurasi yang diperbarui.
2. Perbarui selfManaged.resourceUris di resource AgentGateway untuk mereferensikan URI gateway Secure Web Proxy pengganti.
3. Buat ulang resource EgressRouting Anda agar mengarah ke gateway Secure Web Proxy pengganti.
4. Setelah gateway pengganti merutekan traffic, hapus gateway Secure Web Proxy lama dari resource AgentGateway dan hapus gateway Secure Web Proxy lama.

Secure Web Proxy menolak semua traffic keluar

Semua permintaan keluar dari agen Cloud Run Anda gagal dengan error 403 setelah Anda membuat kebijakan EgressRouting atau melampirkan ExtensionBinding.

Secure Web Proxy menolak semua traffic secara default hingga ALLOW AuthzPolicy di resource Agent Gateway Anda mengizinkannya. Melampirkan ExtensionBinding tidak mengizinkan traffic tanpa ALLOW AuthzPolicy, dan kebijakan yang dilampirkan ke resource Gateway Secure Web Proxy yang mendasarinya akan diabaikan.

Untuk mengizinkan traffic yang sah, lampirkan ALLOW AuthzPolicy yang menargetkan resource Gateway Agen Anda. Untuk mengetahui petunjuknya, lihat Mengizinkan traffic egress dasar pengukuran dan MCP.

Permintaan model keluar gagal dengan error 403

Panggilan keluar dari agen Cloud Run Anda ke endpoint model seperti Vertex AI di REGION-aiplatform.googleapis.com gagal dengan error 403 Forbidden setelah Anda mengonfigurasi kebijakan di Agent Gateway.

Karena --vpc-egress=all merutekan semua traffic container keluar melalui Secure Web Proxy, permintaan model akan gagal jika ALLOW AuthzPolicy Anda hanya cocok dengan metode Model Context Protocol (MCP) atau jika ExtensionBinding Identity-Aware Proxy (IAP) Anda cocok dengan host non-MCP tanpa aturan izin di Unified Access Policy Identity and Access Management (IAM) Anda.

Untuk mengizinkan panggilan model keluar, izinkan endpoint model Anda di ALLOW AuthzPolicy pada resource Agent Gateway Anda. Selain itu, cakupkan matchConditions di ExtensionBinding IAP Anda ke prefix: "urn:mcp" atau tambahkan aturan izin destination.unregistered.host di Unified Access Policy IAM Anda. Untuk mengetahui petunjuknya, lihat Mengizinkan traffic egress dasar dan MCP dan Mengonfigurasi kebijakan egress IAP.

Secure Web Proxy mengabaikan GatewaySecurityPolicyRules

Anda telah membuat GatewaySecurityPolicyRules atau melampirkan AuthzPolicy pada resource Gateway Secure Web Proxy, tetapi tidak berpengaruh pada traffic agen keluar.

Saat Secure Web Proxy dikaitkan dengan resource AgentGateway, Secure Web Proxy hanya menerapkan kebijakan otorisasi dan binding ekstensi yang dilampirkan ke resource AgentGateway. Resource GatewaySecurityPolicyRules atau AuthzPolicy apa pun yang terpasang ke Gateway Secure Web Proxy yang mendasarinya akan diabaikan.

Lampirkan resource AuthzPolicy dan ExtensionBinding ke resource Agent Gateway Anda. Untuk mengetahui petunjuknya, lihat Mengonfigurasi kebijakan di Agent Gateway.

Permintaan keluar gagal dalam pemeriksaan TLS

Permintaan keluar dari agen Cloud Run Anda gagal dengan error TLS pada setiap koneksi.

Akun layanan Secure Web Proxy tidak memiliki roles/privateca.certificateManager di kumpulan Certificate Authority Service Anda.

Berikan roles/privateca.certificateManager di kumpulan CA ke akun layanan Secure Web Proxy Anda. Untuk mengetahui petunjuknya, lihat Membuat akun layanan.

Koneksi keluar yang diperiksa TLS gagal dengan SSLV3_ALERT_HANDSHAKE_FAILURE atau RemoteDisconnected

Permintaan keluar dari agen Anda gagal pada koneksi pertama ke host tujuan dengan SSLV3_ALERT_HANDSHAKE_FAILURE, atau gagal dengan RemoteDisconnected.

Pada koneksi pertama yang diperiksa TLS ke host tujuan, Secure Web Proxy mencetak dan meng-cache sertifikat entitas akhir dari CA Service, yang dapat menyebabkan error handshake sementara. Klien HTTP yang mengirim Connection: close secara default, seperti urllib.request.urlopen, dapat gagal dengan RemoteDisconnected selama intersepsi TLS.

Untuk mencegah error ini dalam kode agen Anda:

• Gunakan klien HTTP yang menggunakan kembali koneksi persisten, seperti httpx.AsyncClient atau requests.Session().
• Konfigurasikan percobaan ulang koneksi dan handshake pada klien HTTP Anda, seperti httpx.AsyncHTTPTransport(retries=2) atau urllib3.util.Retry.

Langkah berikutnya

• Mengelola agen dengan Agent Gateway
• Mengonfigurasi Ambient Networking untuk Cloud Run
• Memecahkan masalah Cloud Run