Traffic keluar Agent Gateway dari Agent Runtime ke jaringan VPC

1. Pengantar

Codelab ini membahas tata kelola egress Agent Gateway untuk agen AI yang mengakses endpoint jarak jauh melalui jaringan VPC pribadi. Agent Gateway yang beroperasi dalam mode keluar (agent-to-anywhere) mendukung konektivitas pribadi ke jaringan VPC menggunakan antarmuka Private Service Connect (PSC). Dalam skenario ini, Agent Runtime menggunakan Agent Gateway untuk mengakses server MCP HTTP yang dapat di-streaming jarak jauh yang dihosting di Cloud Run dengan menggunakan endpoint Private Service Connect (PSC) untuk Google API di jaringan VPC.

Aplikasi AI, mulai dari chatbot mandiri hingga sistem otonom dengan alur kerja multiagen, dapat memanggil alat eksternal secara dinamis. Memberikan akses terkontrol kepada agen untuk membuat kueri database, mengambil konten web, dan menjalankan tindakan sangat penting bagi agen yang aman dan produktif. Namun, di lingkungan perusahaan, mengamankan eksekusi alat agen adalah tantangan. Jika agen memiliki akses jaringan langsung, serangan injeksi perintah atau halusinasi model dapat menyebabkan agen memindahkan data sensitif secara tidak sah atau menjalankan perintah yang merusak.

Untuk mengelola agen otonom dalam skala besar, Agent Gateway menyediakan titik penerapan zero-trust terpusat yang terintegrasi langsung ke dalam arsitektur Agent Platform. Daripada mengandalkan implementasi kustom yang unik untuk setiap aplikasi atau kode agen, Agent Gateway menyediakan perutean jaringan, tata kelola agen, dan keamanan runtime yang diterapkan di tingkat platform.

Saat beroperasi dalam mode keluar (agent-to-anywhere), Agent Gateway mem-proxy semua permintaan keluar dari agen yang dikonfigurasi untuk menggunakan gateway. Setiap permintaan beban kerja agen diautentikasi menggunakan Agent Identity yang unik dan diotorisasi menggunakan kebijakan Identity-Aware Proxy (IAP). Panggilan alat MCP didekode dan diperiksa secara dinamis untuk penegakan kebijakan. Admin keamanan dapat menerapkan izin mendetail secara terpusat untuk memastikan agen hanya dapat memanggil endpoint dan metode yang disetujui.

Yang Anda bangun

  • Agent Gateway dalam mode keluar (agent-to-anywhere)
  • Ekstensi otorisasi Identity-Aware Proxy (IAP)
  • Agen ADK Agent Runtime dengan identitas agen
  • Server MCP HTTP yang dapat di-streaming Cloud Run
  • Agent Registry dengan Google API dan endpoint MCP kustom
  • Kebijakan otorisasi dengan kontrol akses IAM
  • Resource jaringan VPC, zona Cloud DNS, dan endpoint PSC untuk Google API
  • Lampiran jaringan PSC untuk keluar dari Agent Gateway
  • Aturan kebijakan firewall Cloud Next Generation Firewall (NGFW)

figure1

Gambar 1. Arsitektur codelab

Yang Anda pelajari

  • Cara men-deploy Agent Gateway dalam urutan konfigurasi terstruktur
  • Cara mengonfigurasi Agent Gateway dengan konektivitas jaringan VPC pribadi
  • Cara mengubah kebijakan otorisasi dari mode uji coba ke mode diterapkan
  • Cara mendaftarkan endpoint Google API dan server MCP di Agent Registry
  • Cara mengaudit log Agent Gateway untuk memvalidasi tata kelola keluar
  • Cara memvalidasi traffic keluar Agent Gateway menggunakan log Cloud NGFW

Yang Anda perlukan

  • Project Google Cloud yang mengaktifkan penagihan
  • Izin IAM untuk menyediakan layanan jaringan, set data BigQuery, dan resource Platform Agen
  • Shell yang kompatibel dengan POSIX (bash atau zsh) dengan Google Cloud CLI (komponen gcloud dan bq) yang diinstal
  • Alat command line: git, curl, jq (pemroses JSON), Python 3, dan uv (pengelola paket Python)

2. Konsep

Urutan deployment

Codelab ini mengikuti urutan konfigurasi terstruktur sehingga agen memiliki akses ke resource yang diperlukan saat inisialisasi dan konektivitas dapat dikonfirmasi sebelum menerapkan kebijakan akses yang diterapkan.

Codelab ini menggunakan urutan deployment berikut:

  1. Mulai dalam mode DRY_RUN: Pastikan permintaan agen berhasil tiba di gateway dan melewati (mode hanya audit).
  2. Mendaftarkan semua layanan: Mendaftarkan semua komponen agen di Registry Agen dan mengonfirmasi akses alat agen. Gunakan Cloud Logging dan dasbor kejelasan Agent Gateway untuk melihat kueri ke Agent Registry.
  3. Membuat kebijakan otorisasi: Buat dan terapkan kebijakan otorisasi untuk mengizinkan traffic keluar dari agen ke server dan endpoint MCP.
  4. Beralih ke mode ENFORCED: Perbarui kebijakan ekstensi otorisasi untuk menerapkan kebijakan dan memblokir traffic keluar yang tidak sah.

figure2

Gambar 2. Urutan deployment

Topologi perutean keluar

Egress Agent Gateway (agent-to-anywhere) berfungsi sebagai proxy keluar zero-trust terpusat untuk beban kerja agentic. Saat agen membuat permintaan ke alat atau API eksternal, permintaan keluar akan dicegat oleh Agent Gateway dan dievaluasi berdasarkan kebijakan tata kelola sebelum dirutekan ke tujuannya. Dalam arsitektur Platform Agen Google Cloud, Agent Gateway menyediakan konektivitas data plane ke:

  • Jaringan pribadi (VPC): Traffic keluar yang menargetkan API perusahaan internal, microservice, database yang dihosting dalam VPC pribadi, dan jaringan lokal atau lintas cloud yang dapat dijangkau melalui konektivitas hybrid.
  • Jaringan eksternal (Internet): Traffic keluar yang menargetkan layanan web pihak ketiga, API SaaS, atau endpoint publik.
  • Layanan AI & Platform Agen: Traffic keluar yang menargetkan API Google Cloud terkelola, model dasar, endpoint MCP Google (seperti BigQuery), dan layanan tata kelola platform (kebijakan Agent Registry dan IAP).

figure3

Gambar 3. Topologi perutean traffic keluar Agent Gateway

Codelab ini berfokus pada traffic keluar dari agen kustom di Agent Runtime yang menargetkan endpoint PSC untuk Google API yang di-deploy di jaringan VPC. Arsitektur ini memungkinkan akses pribadi ke server MCP yang dihosting di Cloud Run dengan menggunakan lampiran jaringan PSC untuk egress Agent Gateway.

Konektivitas VPC

Egress Agent Gateway (agent-to-anywhere) dapat terhubung ke jaringan VPC dengan menentukan networkConfig: egress: networkAttachment: [URI] dalam file konfigurasi YAML deployment. Setelan ini mengonfigurasi aturan perutean di Agent Gateway untuk mengirim traffic yang di-resolve ke alamat IP pribadi melalui lampiran jaringan PSC ke jaringan VPC.

figure4

Gambar 4. Konektivitas VPC Agent Gateway

Agent Gateway dapat menyelesaikan nama host DNS pribadi menggunakan peering Cloud DNS ke project target dan jaringan VPC tertentu. Zona pribadi yang tercantum dalam konfigurasi dnsPeeringConfig: domains: [NAME] akan menggunakan data Cloud DNS dalam project target. Kueri DNS lainnya akan menggunakan resolver publik Cloud DNS VPC default.

Bagian konsep ini telah selesai... selanjutnya ke bagian Penyiapan.

3. Penyiapan

Peran IAM yang diperlukan

Peran berikut diperlukan untuk membuat resource di Codelab ini:

Kategori

Peran IAM yang diperlukan (ID)

Deskripsi

Pengelolaan API

roles/serviceusage.serviceUsageAdmin

Mengaktifkan layanan Google Cloud API

Jaringan & gateway

roles/networkservices.admin

Menyediakan Agent Gateway

Service extensions

roles/serviceextensions.admin

Mengonfigurasi ekstensi perutean

Keamanan jaringan

roles/networksecurity.admin

Men-deploy kebijakan otorisasi

Agent Registry

roles/agentregistry.admin

Host yang diizinkan katalog

Vertex AI & agen

roles/aiplatform.admin

Men-deploy workload Agent Runtime

Kebijakan keluar

roles/iap.admin

Menerapkan kebijakan roles/iap.egressor

Cloud Storage

roles/storage.admin

Mengelola bucket penyiapan deployment

Log & audit

roles/logging.viewer

Memeriksa rekaman aktivitas dan log audit

Cloud Run Developer

roles/run.developer

Men-deploy layanan Cloud Run

Pembaca Artifact Registry

roles/artifactregistry.reader

Menarik image container

Admin Jaringan Compute

roles/compute.networkAdmin

Mengelola resource jaringan VPC

Administrator DNS

roles/dns.admin

Mengelola zona dan data Cloud DNS

Atau, gunakan peran dasar yang luas seperti roles/admin atau peran lama roles/owner.

Mengakses project Anda

Codelab ini menggunakan satu project Google Cloud. Langkah-langkah konfigurasi menggunakan perintah CLI gcloud dan shell Linux.

Mulailah dengan mengakses command line project Google Cloud Anda:

Menetapkan Project ID

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Mengautentikasi sesi

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Menetapkan variabel lingkungan shell

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-weather"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Jika menjalankan penginstalan Google Cloud SDK yang dikelola sendiri (yaitu, di luar Cloud Shell), update komponen ke versi terbaru.

# update gcloud cli
gcloud components update

Mengaktifkan layanan API

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

Ini mengakhiri bagian penyiapan... selanjutnya ke bagian Network.

4. Jaringan

Jaringan VPC di-deploy menggunakan mode kustom untuk membuat subnet reguler yang mendukung lampiran jaringan PSC untuk Agent Gateway dan egress VPC langsung Cloud Run.

Endpoint PSC untuk Google API di-deploy menggunakan satu /32alamat IPv4 internal global untuk mendukung akses internal pribadi ke Cloud Run. Alamat IP ini tidak ditetapkan dari subnet regional mana pun.

Membuat jaringan

Buat jaringan VPC global.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Buat subnet untuk lampiran jaringan PSC Agent Gateway dan traffic keluar VPC langsung Cloud Run.

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

Membuat aturan firewall

Buat kebijakan dan aturan firewall untuk mengizinkan semua traffic keluar dengan logging yang diaktifkan. Hal ini akan digunakan untuk memantau traffic keluar dari Agent Gateway ke jaringan VPC.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

Membuat lampiran jaringan PSC

Buat lampiran jaringan PSC yang dikonfigurasi untuk menerima secara otomatis koneksi produsen baru.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

Memverifikasi lampiran jaringan PSC

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Membuat endpoint PSC

Buat reservasi alamat IP untuk endpoint PSC global. Alamat yang digunakan di sini tidak boleh berasal dari, atau tumpang-tindih dengan, subnet yang ada.

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

Buat endpoint PSC untuk Google API menggunakan paket all-apis, yang mencakup Cloud Run (run.app).

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

Verifikasi endpoint PSC

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

Buat zona dan data DNS

Buat zona terkelola Cloud DNS pribadi untuk domain run.app.

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

Buat data DNS karakter pengganti A untuk *.run.app. yang mengarah ke alamat IP endpoint PSC.

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

Buat kebijakan Cloud DNS untuk mengaktifkan logging kueri DNS.

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

Buat Cloud NAT

Buat Cloud Router dan Cloud NAT untuk mendukung traffic keluar VPC langsung Cloud Run agar server MCP dapat menjangkau data cuaca eksternal melalui jaringan VPC.

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}

# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

Ini mengakhiri bagian jaringan... selanjutnya ke bagian Gateway.

5. Gateway

Sebelum menerapkan kontrol akses, deploy Agent Gateway dan konfigurasi ekstensi otorisasi dalam mode DRY_RUN. Hal ini memungkinkan panggilan alat keluar berhasil sekaligus mencatat hasil evaluasi untuk tujuan audit.

Di sini, Agent Gateway menggunakan registry regional untuk mendukung resource Agent Runtime regional dan menentukan kolom networkConfig untuk konfigurasi peering DNS dan lampiran jaringan PSC VPC.

Buat gateway

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}-networkConfig.yaml" \
  --location=${REGION}

Verifikasi gateway

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

Pastikan ada endpoint koneksi yang diterima.

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

Bagian gateway ini telah selesai... selanjutnya ke bagian Otorisasi.

6. Otorisasi

Ekstensi otorisasi Agent Gateway untuk Identity-Aware Proxy (IAP) adalah jenis Ekstensi Layanan yang digunakan untuk mendelegasikan keputusan otorisasi untuk semua komunikasi Agent Platform.

  1. Alur delegasi: Saat mencoba memanggil endpoint eksternal atau server MCP, agen akan merutekan permintaan ke Agent Gateway. Alih-alih mengevaluasi akses secara lokal, gateway menggunakan ekstensi otorisasi untuk mengirim panggilan ke layanan evaluasi IAP. IAP mengevaluasi identitas agen (berbasis SPIFFE) terhadap kebijakan IAM resource target di Agent Registry. IAP menampilkan keputusan ALLOW atau DENY kembali ke gateway, yang meneruskan traffic atau memblokirnya dengan kode status HTTP 403 Forbidden.
  2. Mode penerapan: Dalam mode DRY_RUN, IAP mengevaluasi permintaan dan mencatat keputusan di Cloud Logging tanpa memblokir traffic. Dalam mode ENFORCE, setiap permintaan dari agen yang tidak sah atau ke target yang tidak terdaftar akan langsung diblokir.
  3. Lapisan binding: Ekstensi layanan terhubung ke Agent Gateway menggunakan kebijakan otorisasi yang dikonfigurasi dengan profil REQUEST_AUTHZ.

Ekstensi otorisasi

Ekstensi otorisasi menentukan layanan penyedia keamanan dengan setelan konektivitas dan parameter lain yang menentukan cara layanan akan beroperasi dan terintegrasi dengan Agent Gateway.

Buat ekstensi authz

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

Impor ekstensi authz

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

Verifikasi ekstensi authz

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Kebijakan otorisasi

Kebijakan otorisasi mengikat penyedia keamanan (IAP) ke resource gateway target dan menentukan profil intersepsi (REQUEST_AUTHZ).

Buat kebijakan otorisasi

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

Kebijakan otorisasi Bind

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Memverifikasi kebijakan authz

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Bagian otorisasi ini telah selesai... selanjutnya ke bagian Codebase.

7. Codebase

Kode pendaftaran endpoint, server MCP, dan agen yang digunakan untuk Codelab ini dikelola di repositori GitHub Google Cloud jarak jauh. Langkah-langkah berikut akan meng-clone repositori secara lokal, menyalin file yang diperlukan ke struktur direktori kerja saat ini, lalu menghapus file sementara.

Bucket penyiapan penyimpanan dibuat untuk Agent Runtime guna mengupload, mem-build, dan men-deploy kode aplikasi agen yang dipaketkan dan artefak dependensinya.

Mengambil artefak jarak jauh

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_vpc

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

Buat bucket staging

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

Bagian codebase ini telah selesai... selanjutnya ke bagian Registry.

8. Registry

Agent Registry adalah inventaris terpusat dari semua agen, server MCP, dan endpoint (API) dalam ekosistem AI. Selain itu, katalog ini dapat digunakan untuk mencantumkan, menelusuri, dan menemukan alat serta layanan terdaftar lainnya untuk digunakan oleh aplikasi AI. Agent Gateway menggunakan model data registri sebagai framework tata kelola untuk menerapkan kontrol akses keluar. Pemberian peran IAM untuk agen panggilan utama diperiksa berdasarkan kebijakan yang terikat ke resource registry.

Untuk mem-bootstrap lingkungan dan mendukung agen menggunakan berbagai API dan Layanan Google, buat satu layanan endpoint registri yang menggabungkan antarmuka API inti yang diperlukan untuk lab ini. Hal ini akan mempermudah pengelolaan kebijakan tata kelola untuk kumpulan alat umum yang akan digunakan sebagian besar agen.

Mendaftarkan endpoint

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

Memverifikasi pendaftaran endpoint

# list registry regional endpoints
gcloud agent-registry endpoints list --location=${REGION} \
  --flatten="interfaces[]" \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces.url:label=URL)"

Ini mengakhiri bagian pendaftaran... selanjutnya ke bagian server MCP.

9. Server MCP

Memberikan izin IAM untuk deployment

Beri izin ke akun layanan compute default untuk mendukung deployment layanan Cloud Run dari kode sumber.

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

Memverifikasi izin IAM

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Men-deploy server MCP

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

Memberikan izin IAM untuk ingress

Mengikat kebijakan untuk akses pengguna

Beri izin ke akun pengguna (diri sendiri) untuk memanggil server MCP yang dihosting Cloud Run. Langkah ini diperlukan untuk menjalankan skrip pembuatan toolspec.

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

Memverifikasi izin IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Membuat SA kustom untuk pemanggilan MCP

Buat akun layanan kustom untuk memanggil server MCP yang dihosting Cloud Run. Akun layanan ini akan digunakan oleh agen untuk mengambil token ID OIDC yang valid dan ditandatangani Google untuk mengakses Cloud Run.

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"

# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

Mengikat kebijakan untuk akun layanan

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

Memverifikasi izin IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Memberikan izin IAM untuk autentikasi

Berikan peran peniruan identitas akun layanan ke Default Compute Service Account. Hal ini akan memungkinkan agen, yang berjalan di bawah Kredensial Default Aplikasi (ADC), untuk membuat token ID OIDC yang ditandatangani Google atas nama akun layanan pemanggil kustom untuk mengautentikasi panggilan ke Cloud Run.

Mengikat kebijakan untuk autentikasi

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

Memverifikasi izin IAM

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Buat MCP toolspec

Saat mendaftarkan server MCP secara manual, file spesifikasi alat harus disertakan. File toolspec.json mencantumkan semua alat yang disediakan oleh server MCP dan memungkinkan pengguna lain menemukannya setelah terdaftar.

Skrip test_mcp.py, yang disertakan dalam codebase mcp-weather/, membuat file toolspec.json dengan terhubung ke server MCP target (melalui SSE atau HTTP) dan memanggil list_tools() untuk mengambil semua alat yang tersedia yang diekspos oleh server.

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)

# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

Melihat output toolspec yang dihasilkan akan menampilkan atribut MCP yang dapat digunakan Agent Gateway untuk evaluasi dan penerapan kebijakan keluar.

Verifikasi MCP toolspec

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' mcp-weather/toolspec.json

Mengupdate traffic masuk Cloud Run

Ubah setelan ingress untuk layanan Cloud Run sehingga hanya menerima permintaan masuk dari jaringan VPC. Tindakan ini mencegah akses publik langsung ke endpoint MCP dan hanya mengizinkan resource internal untuk mengaksesnya. Traffic yang ditujukan ke endpoint PSC untuk Google API di jaringan VPC akan dianggap sebagai ingress internal dan diizinkan.

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

Memverifikasi traffic masuk Cloud Run

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

Mendaftarkan server MCP

Sekarang setelah memiliki toolspec, daftarkan server MCP dengan Agent Registry regional.

# register mcp server
gcloud agent-registry services create ${MCP_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for weather info" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=mcp-weather/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

Memverifikasi pendaftaran MCP

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

Bagian server MCP ini telah selesai... selanjutnya ke bagian agen ADK.

10. Agen ADK

Agen ADK agent-weather yang di-deploy ke Agent Runtime dikonfigurasi dengan setelan berikut dalam skrip deployment untuk berintegrasi dengan Agent Platform:

  • "identity_type": types.IdentityType.AGENT_IDENTITY untuk menyediakan identitas principal berbasis SPIFFE yang unik untuk agen
  • "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } untuk mengarahkan semua traffic keluar yang dimulai agen ke Agent Gateway untuk evaluasi dan penegakan kebijakan

Agen juga dikonfigurasi untuk menggunakan server MCP dengan meneruskan URL dan akun layanan untuk mengambil token ID OIDC.

Men-deploy agen

# deploy agent runtime workload
uv --directory agent-weather run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Memverifikasi deployment

Mengambil tanda vital deployment

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

Memverifikasi entri registri

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

Verifikasi konfigurasi gateway

# show agent config details (gateway config)
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

Memberikan izin IAM untuk autentikasi

Jika dikonfigurasi untuk menggunakan Agent Identity, agen akan menerima token (format JWT-SVID) dari Security Token Service (STS) gabungan yang ditandatangani oleh sts.googleapis.com (penyedia identitas SPIFFE).

Namun, pemeriksaan pemanggil IAM Cloud Run bawaan hanya memercayai dan dapat memverifikasi token ID OIDC standar yang ditandatangani oleh penerbit OIDC Google utama (accounts.google.com).

Jadi, akun layanan kustom digunakan untuk menukar token STS gabungan (JWT-SVID) yang diperoleh oleh identitas agen dengan token Google (OIDC) standar yang diperoleh menggunakan peniruan identitas akun layanan saat runtime.

Buat binding peran yang diperlukan untuk akun layanan kustom.

Kebijakan pengikatan untuk autentikasi (peniruan identitas)

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

Memverifikasi izin IAM

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Memberikan izin IAM untuk runtime

Pemberian izin IAM untuk runtime memungkinkan agen mengakses layanan AI Platform dan API serta layanan inti Google lainnya menggunakan identitas agen utama berbasis SPIFFE. Kebijakan ini diterapkan menggunakan IAM di tingkat resource.

Buat binding peran yang diperlukan untuk identitas agen.

Mengikat kebijakan untuk akses agen

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Memverifikasi izin IAM

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Ini mengakhiri bagian agen ADK... selanjutnya ke bagian Kebijakan.

11. Kebijakan

Kebijakan otorisasi tata kelola agen mengizinkan traffic dirutekan dari agen AI melalui Agent Gateway dan ke tujuan resource akhir (misalnya, endpoint server MCP pribadi untuk pengambilan data). Setelah traffic mencapai tujuan, izin tingkat layanan atau tingkat aplikasi reguler akan mengizinkan akses data.

Pemberian peran IAM untuk egress Agent Gateway memungkinkan kebijakan akses yang mengizinkan akses identitas utama agen ke resource tujuan terdaftar melalui Agent Gateway. Kebijakan diterapkan di tingkat Agent Gateway dan divalidasi menggunakan kebijakan IAM Identity-Aware Proxy (IAP).

Memberikan peran IAM untuk keluar dari Agent Gateway

Agent Gateway memeriksa permintaan masuk untuk memvalidasi bahwa identitas agen yang memanggil memiliki izin iap.webServiceVersions.egressViaIAP (diberikan oleh peran roles/iap.egressor) pada resource target.

Memberi roles/iap.egressor pada identitas agen atau kumpulan utama Agent Runtime di resource tujuan yang dipilih akan mengizinkan traffic keluar ini. Dalam codelab ini, peran diterapkan ke agen utama yang memberikan izin ke identitas agen Agent Runtime tertentu.

Kebijakan IAM terikat ke resource tujuan seperti yang ditentukan dalam model data Pendaftaran Agen. Resource iap_web/agentRegistry mewakili tingkat "cakupan registri" dalam hierarki IAM. Dengan agentRegistry sebagai induk untuk setiap resource turunan agents, mcpServers, dan endpoints. Dalam codelab ini, kebijakan IAM terikat ke tingkat mcpServer dan endpoint yang menerapkan izin ke resource turunan tertentu.

Mengonfigurasi kebijakan server MCP ke agen

Membuat kebijakan untuk agen ke server mcp

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

CATATAN: etag: harus menampilkan ACAB default karena belum ada kebijakan yang ditentukan.

# create policy config file
cat > cfg/iap-policy-agent-to-mcp.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

Mengikat kebijakan untuk agen ke server MCP

# import policy file
gcloud beta iap web set-iam-policy cfg/iap-policy-agent-to-mcp.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

Memverifikasi izin IAM

# show iap iam policy on mcp server for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

Bagian kebijakan telah selesai... selanjutnya kita akan membahas bagian Audit.

12. Audit

Ekstensi otorisasi Agent Gateway beroperasi dalam mode DRY_RUN. Permintaan keluar diamati dan dicatat dalam log, tetapi tidak diblokir. Menganalisis log sebelum beralih ke mode ENFORCED akan mengonfirmasi kebijakan mana yang perlu dikonfigurasi untuk mengizinkan traffic yang diinginkan.

Menguji kueri agen

Buka jendela browser ke UI konsol Google Cloud, lalu buka:

  • Agent Platform → Agents → Deployments → agent-weather
  • Pilih tab Playground

Atau, jalankan perintah terminal ini dan klik link untuk membuka playground agen:

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

Kirim beberapa kueri pengujian....

  • What is the weather like in London?
  • How warm is it in New York?

Verifikasi bahwa kueri menampilkan respons yang valid.

Menganalisis log audit

Lihat log dan periksa evaluasi kebijakan uji coba.

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'

TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

Mengonfigurasi kebijakan agen ke endpoint

Karena Google API inti untuk agent-weather didaftarkan di bawah layanan endpoint kolektif dalam registry (gapi.core.services), hanya satu kebijakan yang diperlukan untuk memberikan izin keluar agen untuk akses endpoint.

Membuat kebijakan untuk agen ke endpoint

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

Mengikat kebijakan untuk agen ke endpoint

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-agent-to-ep.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

Memverifikasi izin IAM

# show iap iam policy on endpoint for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID}

Ini mengakhiri bagian audit... selanjutnya ke bagian Terapkan.

13. Terapkan

Agen dapat membuat permintaan yang berhasil melalui gateway dalam mode DRY_RUN. Log akses dan endpoint dianalisis untuk membuat serangkaian kebijakan tata kelola yang memungkinkan traffic keluar yang diperlukan dari agen. Sekarang, alihkan ekstensi otorisasi IAP Agent Gateway ke mode ENFORCE dengan memperbarui kebijakan otorisasi.

Memperbarui ekstensi otorisasi

Buat ekstensi authz

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

Impor ekstensi authz

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

Verifikasi ekstensi authz

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

Memperbarui kebijakan otorisasi

Buat kebijakan otorisasi

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

Kebijakan otorisasi Bind

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Memverifikasi kebijakan authz

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Memverifikasi penerapan

Kembali ke Playground agen di UI konsol.

  • Klik tombol "+ Sesi Baru" untuk membuat sesi chat baru

Kirim kueri pengujian tambahan...

  • What is the current temperature in Los Angeles?

Amati permintaan agen ke model dasar Gemini (${REGION}-aiplatform.googleapis.com/...) dan endpoint server MCP (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) diteruskan dengan kode status HTTP 200 OK.

Menganalisis log gateway

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

Pastikan tidak ada permintaan yang diblokir. Cari upaya keluar yang ditolak dengan kode status HTTP 403 Forbidden di log audit gateway.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

Lihat log MCP Agent Gateway dan perhatikan cara payload aplikasi MCP (JSON-RPC) diperiksa untuk mengekspos metadata protokol, termasuk alat mana yang sedang dijalankan.

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

Menganalisis log firewall

Melihat log untuk prioritas aturan kebijakan firewall jaringan 1001.

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

Perhatikan tampilan tingkat jaringan dari berbagai jalur traffic:

  • Agent Gateway berkomunikasi dengan resource jaringan VPC internal menggunakan subnet-${REGION}-agw
  • Server MCP yang dihosting Cloud Run melakukan panggilan ke API cuaca eksternal menggunakan subnet-${REGION}-crun
TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

Menganalisis log DNS

Melihat log kueri DNS untuk permintaan yang diselesaikan oleh zona DNS pribadi (priv-zone-run).

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

Perhatikan bahwa pencarian DNS untuk layanan Cloud Run (mcp-weather...run.app) berasal dari jaringan VPC menggunakan peering DNS dan berhasil diselesaikan ke endpoint PSC internal untuk Google API (240.0.0.10).

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

Hal ini mengakhiri bagian penerapan... selanjutnya ke bagian Pembersihan.

14. Pembersihan 

# delete agent runtime
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete agent resources
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

for ROLE in \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next

# delete gateway resources (policy binding must be deleted synchronously first)
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION} --async

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION} --async

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION} --async

# next

# remove policies
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

# next

# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next

# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next

# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next

# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

Bagian pembersihan ini telah selesai... selanjutnya ke bagian Kesimpulan.

15. Kesimpulan

Selamat! Anda telah berhasil men-deploy Agent Gateway dan mengatur traffic agen AI keluar.

cosmopup

Cosmopup menganggap Codelab sangat keren!

Apa langkah selanjutnya?

Jangan ragu untuk memberikan komentar, pertanyaan, atau koreksi menggunakan formulir masukan ini.

Terima kasih!