Aracı Ağ Geçidi'nin Aracı Çalışma Zamanı'ndan VPC ağına çıkışı

1. Giriş

Bu Codelab'de, özel bir VPC ağı üzerinden uzak uç noktalara erişen yapay zeka aracıları için Agent Gateway çıkış yönetimi ele alınmaktadır. Çıkış (agent-to-anywhere) modunda çalışan Agent Gateway, Private Service Connect (PSC) arayüzlerini kullanarak VPC ağına özel bağlantıyı destekler. Bu senaryoda Agent Runtime, VPC ağındaki Google API'leri için bir Private Service Connect (PSC) uç noktası kullanarak Cloud Run'da barındırılan uzak bir yayınlanabilir HTTP MCP sunucusuna erişmek için Agent Gateway'i kullanır.

Bağımsız chatbot'lardan çoklu ajan iş akışlarına sahip otonom sistemlere kadar yapay zeka uygulamaları, harici araçları dinamik olarak çağırabilir. Ajanlara veritabanlarını sorgulama, web içeriğini getirme ve işlemleri yürütme konusunda kontrollü erişim sağlamak, güvenli ve verimli ajanlar için çok önemlidir. Ancak kurumsal ortamlarda aracı araç yürütme işleminin güvenliğini sağlamak zordur. Bir aracının doğrudan ağ erişimi varsa istem ekleme saldırıları veya model halüsinasyonları, aracının hassas verileri sızdırmasına ya da yıkıcı komutlar çalıştırmasına neden olabilir.

Agent Gateway, özerk aracıları geniş ölçekte yönetmek için doğrudan Agent Platform mimarisine entegre edilmiş merkezi bir sıfır güven zorlama noktası sağlar. Agent Gateway, her uygulamaya veya aracı koduna özgü özel uygulamalara güvenmek yerine platform düzeyinde uygulanan ağ yönlendirme, aracı yönetimi ve çalışma zamanı güvenliği sağlar.

Agent Gateway, çıkış (agent-to-anywhere) modunda çalıştığında, ağ geçidini kullanacak şekilde yapılandırılmış aracıların tüm giden isteklerini proxy'ler. Her aracı iş yükü isteğinin kimliği, benzersiz aracı kimliği kullanılarak doğrulanır ve kimliğe duyarlı proxy (IAP) politikaları kullanılarak yetkilendirilir. MCP aracı çağrıları, politika yaptırımı için dinamik olarak kod çözülür ve incelenir. Güvenlik yöneticileri, aracıların yalnızca onaylanmış uç noktaları ve yöntemleri çağırabilmesini sağlamak için ayrıntılı izinleri merkezi olarak zorunlu kılabilir.

Ne oluşturacaksınız?

  • Çıkışta (agent-to-anywhere) Agent Gateway
  • Identity-Aware Proxy (IAP) yetkilendirme uzantısı
  • Ajan kimliğine sahip Agent Runtime ADK aracısı
  • Cloud Run'da akışa alınabilir HTTP MCP sunucusu
  • Google API ve özel MCP uç noktalarıyla Agent Registry
  • IAM erişim denetimi ile yetkilendirme politikaları
  • VPC ağı kaynakları, Cloud DNS bölgesi ve Google API'leri için PSC uç noktası
  • Agent Gateway çıkışı için PSC ağ eki
  • Cloud Next Generation Firewall (NGFW) güvenlik duvarı politika kuralları

figure1

Şek. 1. Codelab mimarisi

Öğrenecekleriniz

  • Agent Gateway'i yapılandırılmış bir yapılandırma sırasıyla dağıtma
  • Agent Gateway'i özel VPC ağı bağlantısıyla yapılandırma
  • Yetkilendirme politikalarını prova modundan zorunlu kılınan moda geçirme
  • Google API uç noktalarını ve MCP sunucularını Agent Registry'ye kaydetme
  • Çıkış yönetimi doğrulaması için aracı ağ geçidi günlükleri nasıl denetlenir?
  • Cloud NGFW günlüklerini kullanarak aracı ağ geçidi çıkış trafiğini doğrulama

İhtiyacınız olanlar

  • Faturalandırmanın etkin olduğu bir Google Cloud projesi
  • Ağ hizmetleri, BigQuery veri kümeleri ve Agent Platform kaynaklarını sağlama için IAM izinleri
  • Google Cloud KSA'nın (gcloud ve bq bileşenleri) yüklü olduğu POSIX uyumlu bir kabuk (bash veya zsh)
  • Komut satırı araçları: git, curl, jq (JSON işlemcisi), Python 3 ve uv (Python paket yöneticisi)

2. Kavramlar

Dağıtım sırası

Bu codelab, yapılandırılmış bir yapılandırma sırasını takip eder. Böylece, aracılar başlatma sırasında gerekli kaynaklara erişebilir ve zorunlu kılınan erişim politikaları uygulanmadan önce bağlantı doğrulanabilir.

Bu Codelab'de aşağıdaki dağıtım sırası kullanılır:

  1. DRY_RUN modunda başlatma: Aracı isteklerinin ağ geçidine başarıyla ulaştığından ve ağ geçidinden geçtiğinden (yalnızca denetim modu) emin olun.
  2. Tüm hizmetleri kaydetme: Aracı Kaydı'ndaki tüm aracı bileşenlerini kaydedin ve aracı aracına erişimi onaylayın. Agent Registry'ye yapılan sorguları görüntülemek için Cloud Logging ve Agent Gateway gözlemlenebilirlik kontrol panelini kullanın.
  3. Yetkilendirme politikaları oluşturma: Aracıların MCP sunucularına ve uç noktalarına giden trafiğe izin vermek için yetkilendirme politikaları oluşturun ve uygulayın.
  4. ENFORCED moduna geçin: Politikaları zorunlu kılmak ve yetkisiz çıkış trafiğini engellemek için yetkilendirme uzantısı politikasını güncelleyin.

figure2

Şekil 2. Dağıtım sırası

Çıkış yönlendirme topolojisi

Agent Gateway çıkışı (agent-to-anywhere), ajan tabanlı iş yükleri için merkezi bir sıfır güven ilkeli giden proxy görevi görür. Bir aracı, harici bir araç veya API'ye istekte bulunduğunda giden istek, Agent Gateway tarafından yakalanır ve hedefine yönlendirilmeden önce yönetim politikalarına göre değerlendirilir. Google Cloud Agent Platform mimarisinde Agent Gateway, aşağıdaki öğelerle veri düzlemi bağlantısı sağlar:

  • Özel ağlar (VPC): Şirket içi API'leri, mikro hizmetleri, özel VPC'lerde barındırılan veritabanlarını ve karma bağlantı üzerinden erişilebilen şirket içi veya bulutlar arası ağları hedefleyen giden trafik.
  • Harici ağlar (İnternet): Üçüncü taraf web hizmetlerini, SaaS API'lerini veya herkese açık uç noktaları hedefleyen giden trafik.
  • Yapay zeka hizmetleri ve aracı platformu: Yönetilen Google Cloud API'lerini, temel modelleri, Google MCP uç noktalarını (ör. BigQuery) ve platform yönetimi hizmetlerini (aracı kayıt defteri ve IAP politikaları) hedefleyen giden trafik.

figure3

Şekil 3. Agent Gateway çıkış yönlendirme topolojisi

Bu Codelab'in odak noktası, bir VPC ağında dağıtılan Google API'leri için PSC uç noktasını hedefleyen Agent Runtime'daki özel bir aracıdan gelen giden trafiktir. Bu mimari, Agent Gateway çıkışı için PSC ağ eki kullanılarak Cloud Run'da barındırılan MCP sunucusuna özel erişim sağlar.

VPC bağlantısı

Agent Gateway çıkışı (agent-to-anywhere), dağıtım YAML yapılandırma dosyasında networkConfig: egress: networkAttachment: [URI] belirtilerek bir VPC ağına bağlanabilir. Bu ayar, özel IP adreslerine çözümlenen trafiği PSC ağ eki üzerinden VPC ağına göndermek için Agent Gateway'deki yönlendirme kurallarını yapılandırır.

figure4

Şekil 4. Agent Gateway VPC bağlantısı

Agent Gateway, belirtilen bir hedef proje ve VPC ağına Cloud DNS eşlemesi yaparak özel DNS ana makine adlarını çözümleyebilir. dnsPeeringConfig: domains: [NAME] yapılandırmasında listelenen tüm özel bölgeler, hedef projedeki Cloud DNS kayıtlarını kullanır. Diğer tüm DNS sorgularında varsayılan VPC Cloud DNS herkese açık çözümleyici kullanılır.

Kavramlar bölümünü tamamladık. Şimdi Kurulum bölümüne geçiyoruz.

3. Kurulum

Gerekli IAM rolleri

Bu Codelab'deki kaynakları oluşturmak için aşağıdaki roller gereklidir:

Kategori

Gerekli IAM rolü (kimlik)

Açıklama

API yönetimi

roles/serviceusage.serviceUsageAdmin

Google Cloud API hizmetlerini etkinleştirme

Ağ ve ağ geçidi

roles/networkservices.admin

Agent Gateway'i sağlama

Hizmet uzantıları

roles/serviceextensions.admin

Yönlendirme uzantılarını yapılandırma

Ağ güvenliği

roles/networksecurity.admin

Yetkilendirme politikalarını dağıtma

Agent Registry

roles/agentregistry.admin

Katalog için izin verilen ana makineler

Vertex AI ve temsilciler

roles/aiplatform.admin

Agent Runtime iş yüklerini dağıtma

Çıkış politikaları

roles/iap.admin

roles/iap.egressor politikalarını uygulama

Cloud Storage

roles/storage.admin

Dağıtım hazırlama paketlerini yönetme

Günlükler ve denetleme

roles/logging.viewer

İzlemeleri ve denetleme günlüklerini inceleme

Cloud Run Geliştiricisi

roles/run.developer

Cloud Run hizmetlerini dağıtma

Artifact Registry Okuyucu

roles/artifactregistry.reader

Container görüntülerini çekme

İşlem Ağı Yöneticisi

roles/compute.networkAdmin

VPC ağ iletişimi kaynaklarını yönetme

DNS Yöneticisi

roles/dns.admin

Cloud DNS bölgelerini ve kayıtlarını yönetme

Alternatif olarak, roles/admin gibi geniş kapsamlı bir temel rol veya roles/owner gibi eski bir rol kullanın.

Projenize erişme

Bu Codelab'de tek bir Google Cloud projesi kullanılır. Yapılandırma adımlarında gcloud KSA'sı ve Linux kabuk komutları kullanılır.

Google Cloud projenizin komut satırına erişerek başlayın:

Proje kimliğinizi ayarlama

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Oturumun kimliğini doğrulama

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Kabuk ortamı değişkenlerini ayarlama

# 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

Google Cloud SDK'nın kendi kendine yönetilen bir yüklemesini (ör. Cloud Shell dışında) çalıştırıyorsanız bileşenleri en son sürüme güncelleyin.

# update gcloud cli
gcloud components update

API hizmetlerini etkinleştirme

# 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

Kurulum bölümünün sonuna geldik. Şimdi Ağ bölümüne geçiyoruz.

4. Ağ

VPC ağı, Agent Gateway ve Cloud Run doğrudan VPC çıkışı için PSC ağ ekini destekleyen normal alt ağlar oluşturmak üzere özel mod kullanılarak dağıtılır.

Google API'leri için PSC uç noktası, Cloud Run'a özel dahili erişimi desteklemek üzere tek bir /32global dahili IPv4 adresi kullanılarak dağıtılır. Bu IP adresi herhangi bir bölgesel alt ağdan atanmamıştır.

Ağ oluşturma

Global bir VPC ağı oluşturun.

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

Aracı ağ geçidi PSC ağ eki ve Cloud Run doğrudan VPC çıkışı için alt ağlar oluşturun.

# 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

Güvenlik duvarı kuralları oluşturma

Günlüğün etkinleştirildiği tüm çıkış trafiğine izin vermek için bir güvenlik duvarı politikası ve kuralı oluşturun. Bu, Agent Gateway'den VPC ağına çıkan trafiği izlemek için kullanılır.

# 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

PSC ağ eki oluşturma

Yeni üretici bağlantılarını otomatik olarak kabul edecek şekilde yapılandırılmış bir PSC ağ eki oluşturun.

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

PSC ağ ekini doğrulama

# 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}

PSC uç noktası oluşturma

Global PSC uç noktası için bir IP adresi rezervasyonu oluşturun. Burada kullanılan adres, mevcut bir alt ağdan alınamaz veya mevcut bir alt ağ ile çakışamaz.

# 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}

all-apis paketini kullanarak Google API'leri için bir PSC uç noktası oluşturun. Bu paket Cloud Run'ı içerir (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

PSC uç noktasını doğrulama

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

DNS alt bölgesi ve kayıtları oluşturma

run.app alanı için özel bir Cloud DNS tarafından yönetilen alt bölge oluşturun.

# 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}

PSC uç noktasının IP adresini gösteren *.run.app. için joker karakter DNS A kaydı oluşturun.

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

DNS sorgusu günlüğünü etkinleştirmek için bir Cloud DNS politikası oluşturun.

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

Cloud NAT oluşturma

MCP sunucusunun VPC ağı üzerinden harici hava durumu verilerine ulaşması için Cloud Run doğrudan VPC çıkışını desteklemek üzere bir Cloud Router ve Cloud NAT oluşturun.

# 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

Ağ bölümünü tamamladık. Şimdi Ağ Geçidi bölümüne geçiyoruz.

5. Ağ geçidi

Erişim denetimlerini zorunlu kılmadan önce Agent Gateway'i dağıtın ve yetkilendirme uzantısını DRY_RUN modunda yapılandırın. Bu, giden araç çağrılarının başarılı olmasına olanak tanırken denetim amacıyla değerlendirme sonuçlarını da kaydeder.

Burada Agent Gateway, bölgesel Agent Runtime kaynaklarını desteklemek için bölgesel bir kayıt defteri kullanır ve VPC ağı PSC ağı eki ile DNS eşleme yapılandırması için networkConfig alanlarını belirtir.

Ağ geçidi oluştur

# 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}

Ağ geçidini doğrulama

# 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}

Kabul edilen bir bağlantı uç noktası olup olmadığını kontrol edin.

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

Ağ geçidi bölümünü tamamladık. Şimdi Yetkilendirme bölümüne geçiyoruz.

6. Yetkilendirme

Identity-Aware Proxy (IAP) için Agent Gateway yetkilendirme uzantısı, tüm Agent Platform iletişimleri için yetkilendirme kararlarını temsilciye devretmek üzere kullanılan bir hizmet uzantısı türüdür.

  1. Yetkilendirme akışı: Bir aracı, harici bir uç noktayı veya MCP sunucusunu çağırmaya çalıştığında isteği Agent Gateway'e yönlendirir. Ağ geçidi, erişimi yerel olarak değerlendirmek yerine yetkilendirme uzantısını kullanarak IAP değerlendirme hizmetine bir açıklama metni gönderir. IAP, aracı (SPIFFE tabanlı) kimliğini, Aracı Kayıt Defteri'ndeki hedef kaynağın IAM politikasına göre değerlendirir. IAP, ağ geçidine ALLOW veya DENY kararı döndürür. Ağ geçidi, trafiği iletir ya da HTTP 403 Forbidden durum koduyla engeller.
  2. Zorunlu kılma modları: DRY_RUN modunda IAP, istekleri değerlendirir ve trafiği engellemeden kararları Cloud Logging'e kaydeder. ENFORCE modunda, yetkisiz bir aracıdan gelen veya kayıtlı olmayan bir hedefe yönelik tüm istekler hemen engellenir.
  3. Bağlama katmanı: Hizmet uzantısı, REQUEST_AUTHZ profiliyle yapılandırılmış bir yetkilendirme politikası kullanılarak Agent Gateway'e bağlanır.

Yetkilendirme uzantısı

Yetkilendirme uzantısı, bağlantı ayarları ve hizmetin nasıl çalışacağını ve Agent Gateway ile nasıl entegre olacağını tanımlayan diğer parametrelerle birlikte güvenlik sağlayıcı hizmetini belirtir.

Yetkilendirme uzantısı oluşturma

# 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

Yetkilendirme uzantısını içe aktarma

# 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}

Yetkilendirme uzantısını doğrulama

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

Yetkilendirme politikası

Yetkilendirme politikası, güvenlik sağlayıcıyı (IAP) hedef ağ geçidi kaynağına bağlar ve yakalama profilini (REQUEST_AUTHZ) belirtir.

Yetkilendirme politikası oluşturma

# 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

Bind authz politikası

# 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}

Yetkilendirme politikasını doğrulama

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

Yetkilendirme bölümünü tamamladık. Şimdi Kod Tabanı bölümüne geçiyoruz.

7. Kod tabanı

Bu Codelab'de kullanılan aracı, MCP sunucusu ve uç nokta kayıt kodu uzak bir Google Cloud GitHub deposunda tutulur. Aşağıdaki adımlar, depoyu yerel olarak klonlar, gerekli dosyaları mevcut çalışma dizini yapısına kopyalar ve ardından geçici dosyaları temizler.

Agent Runtime'ın paketlenmiş aracı uygulama kodunu ve bağımlı yapılarını yüklemesi, oluşturması ve dağıtması için bir depolama hazırlama paketi oluşturulur.

Uzak yapıları getirme

# 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

Hazırlık paketi oluşturma

# 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)"

Kod tabanı bölümünü tamamladık. Şimdi Kayıt Defteri bölümüne geçiyoruz.

8. Kayıt otoritesi

Agent Registry, yapay zeka ekosistemindeki tüm aracıların, MCP sunucularının ve uç noktaların (API'ler) merkezi bir envanteridir. Ayrıca, yapay zeka uygulamalarının kullanabileceği diğer kayıtlı araç ve hizmetleri listelemek, aramak ve keşfetmek için kullanılabilecek bir katalogdur. Agent Gateway, çıkış erişim denetimini zorunlu kılmak için yönetim çerçevesi olarak kayıt veri modelini kullanır. Arayan ana hesaplar için IAM rolü izinleri, kayıt kaynağına bağlı politika ile karşılaştırılır.

Ortamı başlatmak ve çeşitli Google API'leri ve Hizmetleri'ni kullanarak aracıyı desteklemek için bu laboratuvar için gereken temel API arayüzlerini içeren tek bir kayıt defteri uç nokta hizmeti oluşturun. Bu sayede, çoğu temsilcinin kullanacağı ortak araç grupları için yönetim politikalarını yönetmek kolaylaşır.

Uç noktaları kaydetme

# 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

Uç nokta kaydını doğrulama

# 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)"

Kayıt defteri bölümümüzün sonuna geldik. Şimdi MCP sunucusu bölümüne geçiyoruz.

9. MCP sunucusu

Dağıtım için IAM izinleri verme

Kaynak koddan Cloud Run hizmetlerinin dağıtımını desteklemek için varsayılan işlem hizmeti hesabına izin verin.

# 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"

IAM izinlerini doğrulama

# 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)"

MCP sunucusu dağıtma

# 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

Giriş için IAM izinleri verme

Kullanıcı erişimi için politika bağlama

Cloud Run'da barındırılan MCP sunucusunu çağırmak için kullanıcı hesabına (kendinize) izin verin. Bu, toolspec oluşturma komut dosyasını çalıştırmak için gereklidir.

# 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"

IAM izinlerini doğrulama

# 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)"

MCP çağrısı için özel SA oluşturma

Cloud Run'da barındırılan MCP sunucusunu çağırmak için özel bir hizmet hesabı oluşturun. Bu hizmet hesabı, Cloud Run'a erişmek için aracı tarafından geçerli bir Google imzalı OIDC kimlik jetonunu getirmek üzere kullanılır.

# 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}

Hizmet hesabı için bağlama politikası

# 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}

IAM izinlerini doğrulama

# 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)"

Kimlik doğrulama için IAM izinleri verme

Varsayılan Compute hizmet hesabına hizmet hesabı kimliğine bürünme rolleri atayın. Bu işlem, Application Default Credentials (ADC) altında çalışan aracının, Cloud Run'a yapılan çağrıların kimliğini doğrulamak için özel çağırıcı hizmet hesabı adına Google imzalı OIDC kimlik jetonları oluşturmasına olanak tanır.

Kimlik doğrulama için bağlama politikası

# 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"

IAM izinlerini doğrulama

# 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)"

MCP oluşturma toolspec

MCP sunucusu manuel olarak kaydedilirken bir araç spesifikasyon dosyası eklenmelidir. toolspec.json dosyası, MCP sunucusu tarafından kullanıma sunulan tüm araçları listeler ve kayıtlı olan diğer kullanıcıların bu araçları keşfetmesine olanak tanır.

test_mcp.py komut dosyası, hedef MCP sunucusuna (SSE veya HTTP üzerinden) bağlanıp sunucu tarafından kullanıma sunulan tüm araçları almak için list_tools() işlevini çağırarak mcp-weather/ kod tabanında bulunan bir toolspec.json dosyası oluşturur.

# 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}"

Oluşturulan toolspec çıktısına bakıldığında, Agent Gateway'in çıkış politikası değerlendirmesi ve zorunlu kılma için kullanabileceği MCP özellikleri gösterilir.

MCP'yi doğrulama toolspec

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

Cloud Run girişini güncelleme

Cloud Run hizmetinin giriş ayarını yalnızca VPC ağından gelen istekleri kabul edecek şekilde değiştirin. Bu, MCP uç noktasına doğrudan herkese açık erişimi engeller ve yalnızca dahili kaynakların erişmesine izin verir. VPC ağındaki Google API'leri için PSC uç noktasına yönelik trafik, dahili giriş olarak kabul edilir ve izin verilir.

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

Cloud Run girişini doğrulama

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

MCP sunucusunu kaydetme

Artık toolspec elinizde olduğuna göre MCP sunucusunu bölgesel Agent Registry'ye kaydedin.

# 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

MCP kaydını doğrulama

# 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}

MCP sunucusu bölümümüzün sonuna geldik. Şimdi ADK aracısı bölümüne geçiyoruz.

10. ADK temsilcisi

Agent Runtime'a dağıtılan agent-weather ADK aracısı, Agent Platform ile entegrasyon için dağıtım komut dosyasında aşağıdaki ayarlarla yapılandırılır:

  • "identity_type": types.IdentityType.AGENT_IDENTITY aracılığıyla aracı için benzersiz bir SPIFFE tabanlı asıl kimlik sağlama
  • Tüm giden, temsilci tarafından başlatılan trafiği politika değerlendirmesi ve yaptırımı için temsilci ağ geçidine yönlendirmek üzere "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } }

Aracı, OIDC kimlik jetonunu getirmek için URL ve hizmet hesabı iletilerek MCP sunucusunu kullanacak şekilde de yapılandırılır.

Ajanı dağıtma

# 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

Dağıtımı doğrulama

Dağıtım önemli verilerini getirme

# 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}

Kayıt defteri girişini doğrulama

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

Ağ geçidi yapılandırmasını doğrulama

# 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}'

Kimlik doğrulama için IAM izinleri verme

Bir aracı Aracı Kimliği'ni kullanacak şekilde yapılandırıldığında, birleştirilmiş güvenlik jetonu hizmetinden (STS) sts.googleapis.com (SPIFFE kimlik sağlayıcısı) tarafından imzalanmış bir jeton (JWT-SVID biçiminde) alır.

Ancak yerleşik Cloud Run IAM çağırma denetimi yalnızca ana Google OIDC yayınlayıcısı (accounts.google.com) tarafından imzalanan standart OIDC kimlik jetonlarına güvenir ve bunları doğrulayabilir.

Bu nedenle, aracı kimliği tarafından alınan birleştirilmiş STS jetonunu (JWT-SVID), çalışma zamanında hizmet hesabı kimliğine bürünme kullanılarak alınan standart bir Google (OIDC) jetonuyla değiştirmek için özel bir hizmet hesabı kullanılır.

Özel hizmet hesabı için gereken rol bağlamalarını oluşturun.

Kimlik doğrulama (kimliğe bürünme) için politika bağlama

# 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}"

IAM izinlerini doğrulama

# 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)"

Çalışma zamanı için IAM izinleri verme

Çalışma zamanı için IAM izinleri verme, aracının SPIFFE tabanlı asıl aracı kimliğini kullanarak AI Platform hizmetlerine ve diğer temel Google API'lerine ve hizmetlerine erişmesini sağlar. Bu politikalar, kaynak düzeyinde IAM kullanılarak uygulanır.

Aracı kimliği için gereken rol bağlamalarını oluşturun.

Temsilci erişimi için politikaları bağlama

# 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"

IAM izinlerini doğrulama

# 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)"

ADK aracısı bölümünü tamamladık. Şimdi Politikalar bölümüne geçiyoruz.

11. Politikalar

Aracı yönetimi yetkilendirme politikaları, trafiğin bir yapay zeka aracısından Aracı Ağ Geçidi üzerinden nihai kaynak hedefine (ör. veri alma için özel bir MCP sunucu uç noktası) yönlendirilmesine izin verir. Trafik hedefe ulaştığında, normal hizmet düzeyi veya uygulama düzeyi izinler veri erişimini yetkilendirir.

Agent Gateway çıkışı için IAM rolleri verme, aracı asıl kimliğinin Agent Gateway üzerinden kayıtlı hedef kaynaklara erişmesine izin veren erişim politikalarını etkinleştirir. Politikalar, aracı ağ geçidi düzeyinde uygulanır ve Identity-Aware Proxy (IAP) IAM politikaları kullanılarak doğrulanır.

Aracı Ağ Geçidi çıkışı için IAM rolleri verme

Agent Gateway, gelen istekleri kontrol ederek arayan aracının kimliğinin hedef kaynakta iap.webServiceVersions.egressViaIAP iznine (roles/iap.egressor rolü tarafından verilir) sahip olduğunu doğrular.

Seçilen hedef kaynakta ajan kimliğine veya Agent Runtime asıl kümesine roles/iap.egressor izni verilmesi, bu çıkış trafiğine izin verir. Bu codelab'de rol, belirli Agent Runtime aracı kimliğine izin veren agent ana hesabına uygulanır.

IAM politikaları, Agent Registry veri modelinde tanımlandığı şekilde hedef kaynaklara bağlıdır. iap_web/agentRegistry kaynağı, IAM hiyerarşisinde "kayıt genelinde" bir düzeyi temsil eder. Burada agentRegistry, agents, mcpServers ve endpoints için ayrı alt kaynakların üst öğesi olarak kullanılır. Bu codelab'de, IAM politikası mcpServer ve endpoint düzeylerine bağlıdır. Bu düzeyler, izni belirli alt kaynaklara uygular.

Aracıyı MCP sunucusu politikasına göre yapılandırma

Ajanın MCP sunucusuna erişimi için politika oluşturma

# 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}

NOT: Henüz politika tanımlanmadığı için etag:, varsayılan ACAB değerini döndürmelidir.

# 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

Ajan için politikayı MCP sunucusuna bağlama

# 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}

IAM izinlerini doğrulama

# 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}

Politikalar bölümünü tamamladık. Şimdi Denetim bölümüne geçiyoruz.

12. Denetim

Agent Gateway yetkilendirme uzantısı DRY_RUN modunda çalışıyor. Giden istekler gözlemlenir ve günlüğe kaydedilir ancak engellenmez. ENFORCED moduna geçmeden önce günlükleri analiz etmek, amaçlanan trafiğe izin vermek için hangi politikaların yapılandırılması gerektiğini onaylar.

Test temsilcisi sorguları

Google Cloud Console kullanıcı arayüzü için bir tarayıcı penceresi açın ve şuraya gidin:

  • Agent Platform → Agents → Deployments → agent-weather
  • Playground sekmesini seçin.

Alternatif olarak, bu terminal komutunu yansıtın ve bağlantıyı tıklayarak aracı playground'una gidin:

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

Bazı test sorguları gönderin....

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

Sorguların geçerli yanıtlar döndürdüğünü doğrulayın.

Denetleme günlüklerini analiz etme

Günlükleri görüntüleyin ve deneme amaçlı politika değerlendirmelerini inceleyin.

# 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

Ajanı uç nokta politikasına göre yapılandırma

agent-weather için temel Google API'leri kayıt defterinde toplu bir uç nokta hizmeti (gapi.core.services) altında kaydedildiğinden, uç nokta erişimi için aracı çıkış izinleri vermek üzere yalnızca tek bir politika gerekir.

Ajan-uç nokta politikası oluşturma

# 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

Aracı için politikayı uç noktaya bağlama

# 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}

IAM izinlerini doğrulama

# 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}

Denetim bölümü sona erdi. Şimdi Uygulama bölümüne geçiyoruz.

13. Zorunlu kıl

Aracı, DRY_RUN modunda ağ geçidi üzerinden başarılı istekler gönderebildi. Erişim günlükleri ve uç noktalar, aracıdan gerekli çıkış trafiğine izin veren bir dizi yönetim politikası oluşturmak için analiz edildi. Şimdi yetkilendirme politikasını güncelleyerek Agent Gateway IAP yetkilendirme uzantısını ENFORCE moduna geçirin.

Yetkilendirme uzantısını güncelleme

Yetkilendirme uzantısı oluşturma

# 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

Yetkilendirme uzantısını içe aktarma

# 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}

Yetkilendirme uzantısını doğrulama

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

Yetkilendirme politikasını güncelleme

Yetkilendirme politikası oluşturma

# 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

Bind authz politikası

# 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}

Yetkilendirme politikasını doğrulama

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

Politika uygulamasını doğrulama

Konsol kullanıcı arayüzünde aracı Playground'a geri dönün.

  • Yeni bir sohbet oturumu oluşturmak için "+ Yeni Oturum" düğmesini tıklayın.

Ek bir test sorgusu gönderin...

  • What is the current temperature in Los Angeles?

Gemini temel modeline (${REGION}-aiplatform.googleapis.com/...) ve MCP sunucusu uç noktasına (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) yapılan aracı isteklerinin HTTP 200 OK durum kodlarıyla iletildiğini gözlemleyin.

Ağ geçidi günlüklerini analiz etme

# 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)"

Engellenen istek olup olmadığını kontrol edin. Ağ geçidi denetleme günlüklerinde HTTP 403 Forbidden durum kodlarıyla reddedilen çıkış girişimlerini arayın.

# 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
  )"

Agent Gateway MCP günlüklerini görüntüleyin ve hangi araçların yürütüldüğü de dahil olmak üzere protokol meta verilerini ortaya çıkarmak için MCP uygulama yükünün (JSON-RPC) nasıl incelendiğini not edin.

# 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
  )"

Güvenlik duvarı günlüklerini analiz etme

Ağ güvenlik duvarı politika kuralı önceliği 1001 ile ilgili günlükleri görüntüleyin.

# 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
  )"

Farklı trafik yollarının ağ düzeyindeki görünümüne dikkat edin:

  • subnet-${REGION}-agw kullanarak dahili VPC ağı kaynaklarıyla iletişim kuran aracı ağ geçidi
  • subnet-${REGION}-crun kullanarak harici hava durumu API'lerine çağrı yapan Cloud Run'da barındırılan MCP sunucusu
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

DNS günlüklerini analiz etme

Özel DNS bölgesi tarafından çözülen isteklerin DNS sorgusu günlüklerini görüntüleyin (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
  )"

Cloud Run hizmeti (mcp-weather...run.app) için DNS aramalarının, DNS eşlemesi kullanılarak VPC ağından kaynaklandığını ve Google API'leri için dahili PSC uç noktasına (240.0.0.10) başarıyla çözümlendiğini unutmayın.

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

Bu, zorunlu kılma bölümünün sonuydu. Şimdi Temizleme bölümüne geçiyoruz.

14. Temizleme 

# 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

Temizleme bölümünü tamamladık. Şimdi Sonuç bölümüne geçiyoruz.

15. Sonuç

Tebrikler! Agent Gateway'i başarıyla dağıttınız ve giden yapay zeka aracısı trafiğini yönetiyorsunuz.

cosmopup

Cosmopup, Codelab'lerin çok iyi olduğunu düşünüyor.

Sırada ne var?

Bu geri bildirim formunu kullanarak yorum, soru veya düzeltme önerilerinizi paylaşabilirsiniz.

Teşekkürler!