Agent Engine (ADK) PSC SWP Integration

1. Giriş

Private Service Connect arayüzü, üretici Sanal Özel Bulut (VPC) ağının tüketici VPC ağındaki çeşitli hedeflere bağlantı başlatmasına olanak tanıyan bir kaynaktır. Üretici ve tüketici ağları farklı projelerde ve kuruluşlarda olabilir.

Bir ağ eki, Private Service Connect arayüzünden gelen bağlantıyı kabul ederse Google Cloud, arayüze ağ eki tarafından belirtilen bir tüketici alt ağından IP adresi atar. Tüketici ve üretici ağları bağlıdır ve dahili IP adreslerini kullanarak iletişim kurabilir.

Ağ eki ile Private Service Connect arayüzü arasındaki bağlantı, Private Service Connect uç noktası ile hizmet eki arasındaki bağlantıya benzer ancak iki temel farkı vardır:

  • Ağ eki, üretici ağının tüketici ağına bağlantı başlatmasına (yönetilen hizmet çıkışı) olanak tanırken uç nokta, tüketici ağının üretici ağına bağlantı başlatmasına (yönetilen hizmet girişi) olanak tanır.
  • Private Service Connect arayüz bağlantısı geçişlidir. Bu, bir yapımcı ağının, tüketici ağına bağlı diğer ağlarla iletişim kurabileceği anlamına gelir.

Vertex AI PSC arayüzü erişilebilirliğiyle ilgili dikkat edilmesi gereken noktalar

  • PSC-Interface, VPC ağı tarafından öğrenilen VPC veya şirket içi tabanlı hedeflere trafik yönlendirebilir.
  • Agent Engine tarafından kullanılan ağ ekinden VPC ağına erişilebilirlik kapsamını sınırlamak için çıkış güvenlik duvarı kurallarının uygulanması en iyi uygulamadır.
  • Agent Engine'in ağ eki alt ağından kaynaklanan ağ çıkış trafiğinin kapsamını sınırlamak için bir VPC çıkış güvenlik duvarı kuralı dağıtılmalıdır. Bu kural, diğer tüm giden trafiği reddederken Agent Engine'den SWP'ye gelen trafiğe açıkça izin verir.

Vertex AI PSC arayüzü VPC-SC ile ilgili dikkat edilmesi gereken noktalar

  • VPC Hizmet Kontrolleri etkin olsa bile Agent Engine PSC arayüzünün çalışması için müşteri VPC'sinde internet çıkışı bağlantısı sağlamanız gerekir.

Secure Web Proxy

Güvenli Web Proxy , giden trafiğiniz (HTTP/HTTPS) için ayrıntılı kontrol ve güvenlik sağlayan, yönetilen ve buluta özel bir hizmettir. Merkezi bir ağ geçidi görevi görerek PSC arayüzü ile dağıtılan Agent Engine'den başlatılan bağlantılarda güvenlik politikalarını uygulamanıza olanak tanır. Bu bağlantılar, sanal makineler, GKE, internet ve çoklu bulut ortamları gibi VPC kaynaklarına yöneliktir.

Çözdüğü Sorunlar

  • Veri hırsızlığını önler: Yetkisiz yüklemeleri veya kötü amaçlı sitelerle iletişimi engeller.
  • Uygunluğu zorunlu kılar: Giden trafiğin kuruluşunuzun güvenlik ve veri işleme politikalarına uymasını sağlar.
  • Operasyonel ek yükü azaltır: Tamamen yönetilen bir hizmet olan Secure Web Proxy, kendi proxy sanal makinelerinizi dağıtma, ölçeklendirme veya bakımını yapma ihtiyacını ortadan kaldırır.
  • Derin görünürlük sağlar: Gizli tehditleri tespit etmek için Taşıma Katmanı Güvenliği (TLS) ile şifrelenmiş trafiğin denetlenmesini sağlar.

Daha fazla bilgi için aşağıdaki kaynaklara bakın:

Aracı dağıtma | Vertex AI'da üretken yapay zeka | Google Cloud

Vertex AI kaynakları için Private Service Connect arayüzü oluşturma | Google Cloud

Ne oluşturacaksınız?

Bu eğitimde, ADK kitaplıklarını kullanarak aşağıdakileri yapmak için SWP ile entegre edilmiş Private Service Connect (PSC) arayüzüyle dağıtılan kapsamlı bir Agent Engine oluşturacaksınız:

  • Proxy yapılandırmasında kullanılan SWP'lerin tam etki alan adını çözmek için Agent Engine'de DNS eşlemesini dağıtın.
  • RFC1918 adresiyle tüketicinin VPC'sine dağıtılan güvenli bir web proxy'si aracılığıyla genel bir siteye (https://api.frankfurter.app/) bağlanmaya izin verin.
  • Diğer her şeyi reddederken Ağ Ekleme Alt Ağı'ndan SWP'ye gelen trafiğe izin verin.

Şekil 1

565e9eb07ef18f44.png

Neler öğreneceksiniz?

  • Ağ eki oluşturma
  • Üreticinin PSC arayüzü oluşturmak için ağ eki nasıl kullanabileceği
  • DNS eşleme kullanarak üreticiden tüketiciye iletişimi nasıl kurabilirsiniz?
  • İnternet çıkışı için SWP'yi dağıtma ve kullanma
  • Agent Engine'in ağ erişilebilirliğini azaltmak için çıkış güvenlik duvarı kurallarını tanımlama

Gerekenler

Google Cloud projesi

IAM İzinleri

2. Başlamadan önce

Projeyi, eğitimi destekleyecek şekilde güncelleme

Bu eğitimde, Cloud Shell'de gcloud yapılandırmasının uygulanmasına yardımcı olmak için $değişkenleri kullanılır.

Cloud Shell'de aşağıdakileri yapın:

gcloud config set project [YOUR-PROJECT-NAME]
projectid=YOUR-PROJECT-NAME
echo $projectid

API Etkinleştirme

Cloud Shell'de aşağıdakileri yapın:

gcloud services enable "compute.googleapis.com"
gcloud services enable "aiplatform.googleapis.com"
gcloud services enable "dns.googleapis.com"
gcloud services enable "notebooks.googleapis.com"
gcloud services enable "storage.googleapis.com"
gcloud services enable "iap.googleapis.com"
gcloud services enable "networksecurity.googleapis.com"
gcloud services enable "networkservices.googleapis.com"
gcloud services enable "cloudresourcemanager.googleapis.com"

API'lerin başarıyla etkinleştirildiğini doğrulama

gcloud services list --enabled

3. Tüketici Kurulumu

Tüketici VPC'sini oluşturma

Bu VPC, bir müşteri projesinde bulunur. Bu VPC'de aşağıdaki kaynaklar oluşturulur:

  • Tüketici Alt Ağı
  • Ağa Bağlı Alt Ağ
  • Yalnızca proxy alt ağı
  • Güvenlik Duvarı Kuralları
  • Cloud DNS

Cloud Shell'de aşağıdakileri yapın:

gcloud compute networks create consumer-vpc --project=$projectid --subnet-mode=custom

Tüketici alt ağlarını oluşturma

Cloud Shell'de SWP için alt ağı oluşturun:

gcloud compute networks subnets create swp-subnet --project=$projectid --range=10.10.10.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

Private Service Connect ağ eki alt ağını oluşturma

Cloud Shell'de PSC ağ eki için alt ağı oluşturun:

gcloud compute networks subnets create intf-subnet --project=$projectid --range=192.168.10.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

Bölgesel proxy alt ağını oluşturma

Cloud Shell'de, Secure Web Proxy ve bölgesel dahili/harici uygulama yük dengeleyiciler gibi Envoy tabanlı ürünler için gereken yalnızca proxy alt ağını oluşturun. –purpose işareti REGIONAL_MANAGED_PROXY olarak ayarlanmalıdır:

gcloud compute networks subnets create proxy-subnet \
  --purpose=REGIONAL_MANAGED_PROXY \
  --role=ACTIVE \
  --region=us-central1 \
  --network=consumer-vpc \
  --range=100.100.10.0/26

Not defteri alt ağını oluşturma

Cloud Shell'de not defteri örneği için alt ağı oluşturun:

gcloud compute networks subnets create notebook-subnet --project=$projectid --range=192.168.20.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

4. Secure Web Proxy oluşturma

Güvenli Web Proxy'nin Açık Modu (veya Açık Proxy Yönlendirme Modu), istemci iş yüklerinin yönlendirme proxy'si olarak SWP'nin dahili IP adresini veya tam etki alanı adını ve bağlantı noktasını kullanacak şekilde açıkça yapılandırılması gereken bir dağıtım yöntemidir.

Bu politika, oturum eşleşmesine host() == 'api.frankfurter.app' ve uygulama eşleşmesine request.method == 'GET' dayalı olarak güvenli web proxy'si üzerinden geçen trafiği yöneten kuralları içerir.

Aşağıdaki adımlarda YOUR-PROJECT-ID değerini proje kimliğinizle değiştirdiğinizden emin olun.

Cloud Shell'de bir policy.yaml dosyası oluşturun:

cat > policy.yaml << EOF
name: projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy 
description: "My basic SWP policy" 
EOF

Cloud Shell'de politikayı içe aktarın:

gcloud network-security gateway-security-policies import my-swp-policy \
    --source=policy.yaml \
    --location=us-central1

Güvenli Web Proxy Kuralları Oluşturma

Hangi trafiğe izin verileceğini veya hangi trafiğin reddedileceğini belirtmek için politika içinde kurallar tanımlayın. Kurallar önceliğe göre değerlendirilir.

Cloud Shell'de, aracı motoru tarafından kullanılan internet uç noktasına (api.frankfurter.app) erişime izin vermek için bir rule.yaml dosyası oluşturun:

cat > rule.yaml << EOF
name: "projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy/rules/allow-example"
description: "Allow frankfurter API"
enabled: true
priority: 10
basicProfile: ALLOW
sessionMatcher: "host() == 'api.frankfurter.app'"
EOF

Cloud Shell'de güvenlik politikası kuralı oluşturun:

gcloud network-security gateway-security-policies rules import allow-example \
    --source=rule.yaml \
    --location=us-central1 \
    --gateway-security-policy=my-swp-policy

Güvenli Web Proxy Kuralları Oluşturma

Açık yönlendirme modunda dağıtılan SWP örneği, ağ geçidi YAML dosyasında tanımlandığı gibi, Agent Engine'in ADK proxy yapılandırmasında SWP'nin IP adresini veya FQDN'sini belirtmesi gerekecek şekilde oluşturulmalıdır. Bu yapılandırma, örneği ilgili politika, ağ ve alt ağa da bağlar.

Cloud Shell'de, SWP'yi dağıtmak için kullanılan bir gateway.yaml dosyası oluşturun.

Aşağıdaki değişkenleri ortamınızın ayrıntılarıyla güncelledikten sonra YAML dosyasını kaydettiğinizden emin olun: PROJECT_ID, REGION, NETWORK_NAME ve PROXY_ONLY_SUBNET_NAME. Belirtilen 8888 numaralı bağlantı noktası, Agent Engine'deki proxy yapılandırmasına eşlenen dış tünel bağlantı noktasıdır.

cat > gateway.yaml << EOF
name: "projects/$projectid/locations/us-central1/gateways/my-swp-instance"
type: SECURE_WEB_GATEWAY
ports: [8888]
addresses: ["10.10.10.5"]
gatewaySecurityPolicy: "projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy"
network: "projects/$projectid/global/networks/consumer-vpc"
subnetwork: "projects/$projectid/regions/us-central1/subnetworks/swp-subnet"
routingMode: EXPLICIT_ROUTING_MODE
EOF

Cloud Shell'de ağ geçidini içe aktarın:

gcloud network-services gateways import my-swp-instance \
    --source=gateway.yaml \
    --location=us-central1

5. Private Service Connect ağ eki

Ağ ekleri, Private Service Connect arayüzünün tüketici tarafını temsil eden bölgesel kaynaklardır. Bir ağ ekiyle tek bir alt ağ ilişkilendirirsiniz ve üretici, bu alt ağdan Private Service Connect arayüzüne IP'ler atar. Alt ağ, ağ ekiyle aynı bölgede olmalıdır. Ağ eki, üretici hizmetiyle aynı bölgede olmalıdır.

Ağ eki oluşturma

Cloud Shell'de ağ ekini oluşturun.

gcloud compute network-attachments create psc-network-attachment \
    --region=us-central1 \
    --connection-preference=ACCEPT_AUTOMATIC \
    --subnets=intf-subnet

Ağ eklerini listeleme

Cloud Shell'de ağ ekini listeleyin.

gcloud compute network-attachments list

Ağ eklerini açıklama

Cloud Shell'de ağ ekini açıklayın.

gcloud compute network-attachments describe psc-network-attachment --region=us-central1

Üretici, Private Service Connect arayüzünü oluştururken kullanılacak PSC ağ eki adını (psc-network-attachment) not edin.

PSC ağ eki URL'sini Cloud Console'da görüntülemek için şuraya gidin:

Network Services → Private Service Connect → Network Attachment → psc-network-attachment

15f80b46c3a0332d.png

6. Özel DNS bölgesi

demo.com için bir Cloud DNS bölgesi oluşturacak ve bu bölgeyi SWP'lerinizin IP adreslerini gösteren bir A kaydıyla dolduracaksınız. Daha sonra, DNS eşleme Agent Engine'de dağıtılacak ve tüketicinin DNS kayıtlarına erişime izin verecek.

Cloud Shell'de, demo.com DNS adını oluşturan aşağıdaki işlemi yapın.

gcloud dns --project=$projectid managed-zones create private-dns-codelab --description="" --dns-name="demo.com." --visibility="private" --networks="https://compute.googleapis.com/compute/v1/projects/$projectid/global/networks/consumer-vpc"

DNS A kaydı için kullanılan SWP'nin IP adreslerini alın ve saklayın.

Cloud Shell'de, swp, my-swp-instance için bir açıklama işlemi gerçekleştirin:

gcloud network-services gateways describe my-swp-instance --location=us-central1

Cloud Shell'de SWP için kayıt kümesini (swp.demo.com) oluşturun. IP adresini ortamınızın çıkışına göre güncellediğinizden emin olun.

gcloud dns --project=$projectid record-sets create swp.demo.com. --zone="private-dns-codelab" --type="A" --ttl="300" --rrdatas="10.10.10.5"

Güvenlik Duvarı Yapılandırması

PSC arayüzünden erişime izin vermek için bir Cloud Firewall kuralı oluşturun.

Aşağıdaki bölümde, PSC Ağ Eklentisi'nden kaynaklanan trafiğin Tüketici VPC'sindeki SWP alt ağına erişmesine izin veren bir güvenlik duvarı kuralı oluşturun. Güvenliği artırmak için SWP IP adresini tek hedef olarak belirtebilirsiniz.

Cloud Shell'de, ağ ekinden SWP'ye erişime izin veren çıkış güvenlik duvarı kuralını oluşturun:

gcloud compute firewall-rules create allow-access-to-swp \
    --network=consumer-vpc \
    --action=ALLOW \
    --rules=ALL \
    --direction=EGRESS \
    --priority=1000 \
    --source-ranges="192.168.10.0/28" \
    --destination-ranges="10.10.10.5/32" \
    --enable-logging

Cloud Shell'de, ağ ekinden gelen tüm trafiği reddeden çıkış güvenlik duvarı kuralını oluşturun:

gcloud compute firewall-rules create deny-all \
    --network=consumer-vpc \
    --action=DENY \
    --rules=ALL \
    --direction=EGRESS \
    --priority=65534 \
    --source-ranges="192.168.10.0/28" \
    --destination-ranges="0.0.0.0/0" \
    --enable-logging

7. Tehdit istihbaratını sağlamak için VPC ağına yönelik bir güvenlik duvarı politikası oluşturun:

Aşağıdaki bölümde, Google'ın yönetilen tehdit listelerinden yararlanarak bilinen kötü amaçlı siteleri, SWP tarafından trafik alınmadan önce engellemenize olanak tanıyan bir güvenlik duvarı politikası oluşturun.

Cloud Shell'de genel güvenlik duvarı politikasını oluşturun:

gcloud compute network-firewall-policies create psc-secure-policy \
    --global \
    --description="Policy to protect VPC with Threat Intelligence"

Cloud Shell'de politikayı VPC'nizle ilişkilendirin:

gcloud compute network-firewall-policies associations create \
    --firewall-policy=psc-secure-policy \
    --network=consumer-vpc \
    --name=psc-swp-association \
    --global-firewall-policy

Cloud Shell'de tehdit istihbaratı kurallarını ekleyin:

Bu kurallar, aracıdan gelen trafiği başlatmadan önce bilinen kötü amaçlı aktörlere yönelik trafiği düşürür. Bu örnekte, yetkisiz kaynak kullanımını önlemek için Tor çıkış düğümlerini (çıkış) engelleme, bilinen kötü amaçlı IP'leri (çıkış) engelleme, bilinen anonim proxy'leri(çıkış) engelleme ve kripto madencilerini (çıkış) engelleme kuralları ekledik.

gcloud compute network-firewall-policies rules create 100 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-tor-exit-nodes \
    --layer4-configs=all \
    --enable-logging \
    --description="Block anonymous Tor traffic" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 110 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-known-malicious-ips \
    --layer4-configs=all \
    --enable-logging \
    --description="Block known botnets and malware sources" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 120 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-anon-proxies \
    --layer4-configs=all \
    --enable-logging \
    --description="Block Known Anonymous Proxies" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 130 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-crypto-miners \
    --layer4-configs=all \
    --enable-logging \
    --description="Block Crypto Miners (Prevent unauthorized resource usage)" \
    --global-firewall-policy

8. Jupyter Notebook oluşturma

Aşağıdaki bölümde, Jupyter Notebook oluşturma konusunda size yol gösterilir. Bu not defteri, internet çıkışı için açık bir proxy'yi hedefleyen Agent Engine'i dağıtmak için kullanılır.

Kullanıcı tarafından yönetilen hizmet hesabı oluşturma

Aşağıdaki bölümde, eğitimde kullanılan Vertex AI Workbench örneğiyle ilişkilendirilecek bir hizmet hesabı oluşturacaksınız.

Eğitimde, hizmet hesabına aşağıdaki roller uygulanır:

Cloud Shell'de hizmet hesabını oluşturun.

gcloud iam service-accounts create notebook-sa \
    --display-name="notebook-sa"

Cloud Shell'de hizmet hesabını Storage Admin rolüyle güncelleyin.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/storage.admin"

Cloud Shell'de hizmet hesabını Vertex AI Kullanıcısı rolüyle güncelleyin.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/aiplatform.user"

Cloud Shell'de hizmet hesabını Artifact Registry Yöneticisi rolüyle güncelleyin.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"

Cloud Shell'de, not defteri hizmet hesabının varsayılan Compute Engine hizmet hesabını kullanmasına izin verin.

gcloud iam service-accounts add-iam-policy-binding \
    $(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')-compute@developer.gserviceaccount.com \
    --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountUser"

9. Vertex AI Workbench örneği oluşturma

Aşağıdaki bölümde, daha önce oluşturulan hizmet hesabını (notebook-sa) içeren bir Vertex AI Workbench örneği oluşturun.

Cloud Shell'de private-client örneğini oluşturun.

gcloud workbench instances create workbench-tutorial --vm-image-project=cloud-notebooks-managed --vm-image-family=workbench-instances --machine-type=n1-standard-4 --location=us-central1-a --subnet-region=us-central1 --subnet=notebook-subnet --disable-public-ip --shielded-secure-boot=true --shielded-integrity-monitoring=true --shielded-vtpm=true --service-account-email=notebook-sa@$projectid.iam.gserviceaccount.com

Bu not defteri örneğinden gelen trafiği yönlendirmek için mevcut güvenli web proxy'sine başka bir kural ekleyin:

Cloud Shell'de bir metin düzenleyici kullanarak rule-notebook.yaml dosyasını oluşturun. YAML'yi proje kimliğinizle güncellediğinizden emin olun.

cat > rule-notebook.yaml << EOF
name: projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy/rules/allow-notebook-subnet
description: Allow Internet access for notebook subnet
enabled: true
priority: 2
basicProfile: ALLOW
sessionMatcher: inIpRange(source.ip,'192.168.20.2')
EOF

Cloud Shell'de güvenlik politikası kuralı oluşturun:

gcloud network-security gateway-security-policies rules import allow-notebook-subnet \
    --source=rule-notebook.yaml \
    --location=us-central1 \
    --gateway-security-policy=my-swp-policy

10. Vertex AI Service Agent Update

Vertex AI, PSC arayüzünü oluşturmak için kullanılan PSC Ağ Eki alt ağından IP adresi alma gibi işlemleri sizin adınıza gerçekleştirir. Vertex AI, bunu yapmak için Ağ Yöneticisi izni gerektiren bir hizmet aracısı (aşağıda listelenmiştir) kullanır:

service-$projectnumber@gcp-sa-aiplatform.iam.gserviceaccount.com

Cloud Shell'de proje numaranızı alın.

gcloud projects describe $projectid | grep projectNumber

Cloud Shell'de proje numaranızı ayarlayın.

projectnumber=YOUR-PROJECT-NUMBER

Cloud Shell'de AI Platform için bir hizmet hesabı oluşturun. Projenizde mevcut bir hizmet hesabınız varsa bu adımı atlayın.

gcloud beta services identity create --service=aiplatform.googleapis.com --project=$projectnumber

Cloud Shell'de, hizmet aracısı hesabını compute.networkAdmin rolüyle güncelleyin.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:service-$projectnumber@gcp-sa-aiplatform.iam.gserviceaccount.com" --role="roles/compute.networkAdmin"

Cloud Shell'de hizmet aracısı hesabını dns.peer rolüyle güncelleyin.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:service-$projectnumber@gcp-sa-aiplatform.iam.gserviceaccount.com" --role="roles/dns.peer"

Varsayılan Hizmet Hesabı Güncellemesi

Varsayılan hizmet hesabınıza Vertex AI'a erişim izni verin. Erişim değişikliğinin geçerlilik kazanması biraz zaman alabilir.

Cloud Shell'de varsayılan hizmet hesabını aiplatform.user rolüyle güncelleyin.

gcloud projects add-iam-policy-binding $projectid \
  --member="serviceAccount:$projectnumber-compute@developer.gserviceaccount.com" \
    --role="roles/aiplatform.user"

11. Agent Engine'i dağıtma

Not: Bu bölümdeki görevleri tamamlamak için GCP Console ve JupyterLab not defterini kullanacağız.

Aşağıdaki bölümde, şu görevleri gerçekleştiren bir not defteri oluşturacaksınız:

  • Döviz kuru verilerini almak için Frankfurter API'yi (https://api.frankfurter.app/) kullanır.
  • FQDN swp.demo.com kullanılarak tüketicilerin VPC'sindeki SWP'yi hedefleyen açık bir proxy'ye (proxy_server) referans verir.
  • dnsPeeringConfigs "domain": "demo.com." öğesini tanımlayın.

Eğitim işini Vertex AI Workbench örneğinde çalıştırma

  • Google Cloud Console'da Vertex AI → Workbench
  • Vertex AI Workbench örneğinizin adının (workbench-tutorial) yanındaki Open JupyterLab'i (JupyterLab'i aç) tıklayın. Vertex AI Workbench örneğiniz JupyterLab'de açılır.
  • File > New > Notebook adlı müşteriyi seç
  • Kernel > Python 3 adlı müşteriyi seç

Gerekli Python kitaplıklarını yükleyin: pyyaml, google-cloud-aiplatform, cloudpickle, google-cloud-api-keys ve langchain-google-vertexai dahil olmak üzere Agent Engine için gerekli kitaplıkları yükleyin.

JupyterLab not defterinizde yeni bir hücre oluşturun ve aşağıdaki kodu çalıştırarak SWP'lerin IP adresini belirtin.

7b827a6a38bb5afc.png

!pip install --proxy http://10.10.10.5:8888 --upgrade google-cloud-aiplatform[agent_engines,adk]

Aşağıdaki kod snippet'inde ortamınıza göre aşağıdaki değişkenleri tanımlayın:

  • PROJECT_ID
  • BUCKET_NAME
  • AGENT_NAME

Bu laboratuvarda, genel olarak kullanılabilen depolama paketinizi başlatmak ve yapılandırmak için BUCKET_NAME ve AGENT_NAME değişkenlerini kullanacaksınız.

Aşağıdaki bölümde, ad çözümlemesi için DNS eşlemesi gerektiren PROXY_SERVER (ör.swp.demo.com) tanımlanır. Yapılandırmada, AGENT_PEER_DOMAIN, AGENT_PEER_NETWORK içindeki önceki bir adımda oluşturulan özel DNS bölgesi olan consumer-vpc'ye karşılık gelen demo.com olarak dağıtılır.

JupyterLab not defterinizde yeni bir hücre oluşturup aşağıdakileri çalıştırın:

# --- Fundamental Project Configuration ---
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-central1" # e.g., "us-central1"
BUCKET_NAME = "YOUR_BUCKET_NAME" # A GCS bucket in the same location

# --- Agent Configuration ---
AGENT_NAME = "YOUR_AGENT_NAME"
MODEL = "gemini-2.5-flash" # Or another suitable model

# --- Network and Proxy Configuration ---
# The agent will call the Frankfurter API via this proxy
PROXY_SERVER = "http://swp.demo.com:8888"

# --- Deployment Configuration (PSC & DNS Peering) ---
# This should be a pre-existing Network Attachment
NETWORK_ATTACHMENT_NAME = f"projects/{PROJECT_ID}/regions/{LOCATION}/networkAttachments/psc-network-attachment"
# Optional DNS Peering config
AGENT_PEER_DOMAIN = "demo.com."
AGENT_PEER_NETWORK = "consumer-vpc"

# --- Initialize Vertex AI SDK ---
import vertexai
STAGING_BUCKET = f"gs://{BUCKET_NAME}"

vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET)

print(f"Vertex AI SDK initialized for project {PROJECT_ID} in {LOCATION}.")

JupyterLab not defterinizde yeni bir hücre oluşturun ve aşağıdakileri çalıştırın.

!adk create $AGENT_NAME --model=$MODEL --project=$PROJECT_ID --region=$LOCATION

JupyterLab not defterinizde yeni bir hücre oluşturun ve SWP'lerin FQDN'si ve bağlantı noktasına karşılık gelen proxy değişkenini oluşturmak için aşağıdakileri çalıştırın.

import os
os.environ["PROXY_SERVER_URL"] = "http://swp.demo.com:8888"

Aşağıdaki kod hücresinde, SWP'yi belirterek Agent Engine'in internet uç noktası api.frankfurter.app'e erişmesi için açık proxy yapılandırması gösterilmektedir. Bu yapılandırmada, os.environ["PROXY_SERVER_URL"]. ile eşlenen PROXY_SERVER_TO_USE kullanılır.

import requests
# Use the globally defined proxy server URL
    proxies = {
       "http": PROXY_SERVER_TO_USE,
       "https": PROXY_SERVER_TO_USE,
    }
    try:
        response = requests.get(
            f"https://api.frankfurter.app/{currency_date}",
            params={"from": currency_from, "to": currency_to},
            proxies=proxies,
) 
response.raise_for_status() 
print(response.json()) 
except requests.exceptions.RequestException as e: print(f"An error occurred: {e}")

JupyterLab not defterinizde yeni bir hücre oluşturun ve para birimi değişimi hedefleme için araç uygulamasını tanımlayan aşağıdaki kodu çalıştırın: api.frankfurther.app.

%%writefile $AGENT_NAME/agent.py
from google.adk.agents.llm_agent import Agent
import os
import requests


# Get Proxy Server URL
# This is the VM's FQDN to reach the proxy vm in the consumers network
if "PROXY_SERVER_URL" not in os.environ:
    raise ValueError("Missing required environment variable: PROXY_SERVER_URL is not set.")
PROXY_SERVER_TO_USE = os.environ["PROXY_SERVER_URL"]

# Mock tool implementation
def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """Retrieves the exchange rate between two currencies on a specified date.

    Uses the Frankfurter API (https://api.frankfurter.app/) to obtain
    exchange rate data.

    Args:
        currency_from: The base currency (3-letter currency code).
            Defaults to "USD" (US Dollar).
        currency_to: The target currency (3-letter currency code).
            Defaults to "EUR" (Euro).
        currency_date: The date for which to retrieve the exchange rate.
            Defaults to "latest" for the most recent exchange rate data.
            Can be specified in YYYY-MM-DD format for historical rates.

    Returns:
        dict: A dictionary containing the exchange rate information.
            Example: {"amount": 1.0, "base": "USD", "date": "2023-11-24",
                "rates": {"EUR": 0.95534}}
    """
    # Use the globally defined proxy server URL
    proxies = {
       "http": PROXY_SERVER_TO_USE,
       "https": PROXY_SERVER_TO_USE,
    }
    
    try:
        response = requests.get(
            f"https://api.frankfurter.app/{currency_date}",
            params={"from": currency_from, "to": currency_to},
            proxies=proxies,
        )
        response.raise_for_status()  # Raise an error for bad responses
        return response.json()
    except Exception as e:
        return f"An unexpected error occurred: {e}"

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description="Provides the currency exchange rates between two currencies",
    instruction="You are a helpful assistant that provides the currency exchange rates between two currencies. Use the 'get_exchange_rate' tool for this purpose.",
    tools=[get_exchange_rate],
)

JupyterLab not defterinizde yeni bir hücre oluşturun ve aşağıdakileri çalıştırın.

# 1. Set your variables
CURRENCY_DATE="latest"
CURRENCY_FROM="USD"
CURRENCY_TO="EUR"
PROXY_SERVER="http://swp.demo.com:8888"

# 2. Run the curl command
!curl -x "$PROXY_SERVER" "https://api.frankfurter.app/$CURRENCY_DATE?from=$CURRENCY_FROM&to=$CURRENCY_TO"

JupyterLab not defterinizde yeni bir hücre oluşturun ve DNS eşlemenin yanı sıra Agent Engine tarafından kullanılan psc arayüz yapılandırmasını çağıran aşağıdaki kodu çalıştırın.

import json
import os

CONFIG_FILE_PATH = os.path.join(AGENT_NAME, ".agent_engine_config.json")
# Create your config as a Python dictionary ---
config_data = {
    "requirements": [
        "google-cloud-aiplatform[agent_engines,adk]",
        "requests",
    ],
    "psc_interface_config": {
        "network_attachment": NETWORK_ATTACHMENT_NAME,
        "dns_peering_configs": [
            {
                "domain": AGENT_PEER_DOMAIN,
                "target_project": PROJECT_ID,
                "target_network": AGENT_PEER_NETWORK,
            },
        ],
    },
}

# Write the dictionary to a JSON file ---
os.makedirs(AGENT_NAME, exist_ok=True) # Ensure the directory exists
with open(CONFIG_FILE_PATH, 'w') as f:
    json.dump(config_data, f, indent=4)

print(f"Successfully created {CONFIG_FILE_PATH} with your variables.")

JupyterLab not defterinizde yeni bir hücre oluşturun ve aşağıdakileri çalıştırın.

import json
import os

CONFIG_FILE_PATH = os.path.join(AGENT_NAME, ".agent_engine_config.json")
# Create your config as a Python dictionary ---
config_data = {

    "psc_interface_config": {
        "network_attachment": NETWORK_ATTACHMENT_NAME,
        "dns_peering_configs": [
            {
                "domain": AGENT_PEER_DOMAIN,
                "target_project": PROJECT_ID,
                "target_network": AGENT_PEER_NETWORK,
            },
        ],
    },
}

# Write the dictionary to a JSON file ---
os.makedirs(AGENT_NAME, exist_ok=True) # Ensure the directory exists
with open(CONFIG_FILE_PATH, 'w') as f:
    json.dump(config_data, f, indent=4)

print(f"Successfully created {CONFIG_FILE_PATH} with your variables.")

JupyterLab not defterinizde yeni bir hücre oluşturun ve aşağıdakileri çalıştırın.

%%writefile $AGENT_NAME/.env

GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=1


PROXY_SERVER_URL=http://swp.demo.com:8888

JupyterLab not defterinizde yeni bir hücre oluşturun ve aşağıdaki kodu çalıştırarak temsilciyi oluşturun.

!adk deploy agent_engine $AGENT_NAME --staging_bucket=$STAGING_BUCKET --env_file=$AGENT_NAME/.env --agent_engine_config_file=$AGENT_NAME/.agent_engine_config.json --display_name=$AGENT_NAME

Hücre yürütüldüğünde bir akıl yürütme motoru kimliği oluşturulur. Sonraki adım için oluşturulan kimliğe ihtiyacınız olacak. Bu örnekte kimlik 3235268984265768960'dır.

✅ Created agent engine: projects/9315891080/locations/us-central1/reasoningEngines/3235268984265768960

JupyterLab not defterinizde yeni bir hücre oluşturun ve aşağıdakileri çalıştırın. Önceki çıktıda yer alan proje numaranız ve Agent Engine akıl yürütme kimliğinizle güncellemeyi unutmayın:

from vertexai import agent_engines
remote_app = agent_engines.get("projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENTER_YOUR_ID")

JupyterLab not defterinizde yeni bir hücre oluşturun ve aşağıdakileri çalıştırın.

def print_event_nicely_with_thoughts(event):
    """
    Parses and prints streaming query events, including thoughts.
    """
    try:
        content = event.get('content', {})
        role = content.get('role')
        parts = content.get('parts', [{}])

        if not parts:
            print("...")
            return

        part = parts[0] # Get the first part

        # Event 1: Model is thinking (calling a tool or just text)
        if role == 'model':

            # Check for and print any explicit 'thought' text
            if 'thought' in part:
                print(f"🧠 Thought: {part['thought']}")

            # Check for a function call
            if 'function_call' in part:
                # If we haven't *already* printed an explicit thought,
                # print a generic one.
                if 'thought' not in part:
                    print("🧠 Thinking... (decided to use a tool)")

                call = part['function_call']
                print(f"   🔧 Tool Call: {call.get('name')}()")
                print(f"      Args: {call.get('args')}")

            # Check for the final text answer
            elif 'text' in part:
                text = part.get('text', '')
                print(f"\n💬 Model: {text}")

        # Event 2: The tool returns its result
        elif role == 'user' and 'function_response' in part:
            resp = part['function_response']
            print(f"⚙️ Tool Response (from {resp.get('name')}):")
            print(f"   Output: {resp.get('response')}")

        # Other event types (like progress messages)
        else:
            print("...") # Show progress for other events

    except Exception as e:
        print(f"Error processing event: {e}")
        # print(f"Raw event: {event}") # Uncomment to debug



for event in remote_app.stream_query(
    user_id="u_456",
    # session_id=remote_session["id"],
    message="Provide USD to INR conversion rate",
):
    print_event_nicely_with_thoughts(event)

USD-INR döviz kuruna göre SWP üzerinden public uç nokta api.frankfurther.app ile bağlantıyı doğrulayan başarılı bir yürütme örneği.

f9f925983ab5cc9d.png

12. PSC Arayüzü Doğrulaması

Ayrıca, aşağıdaki adrese giderek Agent Engine tarafından kullanılan ağ ekleme IP'lerini de görüntüleyebilirsiniz:

Ağ Hizmetleri → Private Service Connect → Ağ Eki → psc-network-attachment

Kiracı projesini seçin (proje adı -tp ile biter).

c9c412334a7f5ad9.png

Vurgulanan alan, PSC Ağ Eki'nden Agent Engine tarafından kullanılan IP adresini gösterir.

e94c6c03fb51f7fe.png

13. SWP - Cloud Logging Doğrulaması

SWP tarafından gerçekleştirilen internet çıkışını doğrulamak için Cloud Logging'i görüntüleyebilirsiniz. Bunun için şuraya gidin:

İzleme → Günlük Gezgini

Sorguyu ekleyin: resource.type=" networkservices.googleapis.com/Gateway" ardından Sorguyu Çalıştır'ı tıklayın. Aşağıda, hedef uç nokta olan api.frankfurter.app'i doğrulayan bir örnek verilmiştir.

f53831ef8ec663db.png

fc154a5b22da2a87.png

Aşağıdaki Cloud Logging örneği şunları doğrular:

Destination_range: Agent Engine PSC Arayüz IP Adresi

Source_range: Proxy Only Subnet Dest_ip: Secure Web Proxy IP Address

Cloud Logging sorgusu için project_id değerini değiştirdiğinizden emin olun.

logName:("projects/project_id/logs/compute.googleapis.com%2Ffirewall") AND jsonPayload.rule_details.reference:("network:consumer-vpc/firewall:allow-access-to-swp")

{
  "insertId": "1j9ym95fmu8g6o",
  "jsonPayload": {
    "vpc": {
      "project_id": "XXXXXXXXXXXXX",
      "subnetwork_name": "intf-subnet",
      "vpc_name": "consumer-vpc"
    },
    "rule_details": {
      "destination_range": [
        "10.10.10.5/32"
      ],
      "reference": "network:consumer-vpc/firewall:allow-access-to-swp",
      "priority": 1000,
      "source_range": [
        "192.168.10.0/28"
      ],
      "direction": "EGRESS",
      "ip_port_info": [
        {
          "ip_protocol": "ALL"
        }
      ],
      "action": "ALLOW"
    },
    "disposition": "ALLOWED",
    "remote_instance": {
      "region": "us-central1"
    },
    "remote_vpc": {
      "vpc_name": "consumer-vpc",
      "project_id": "XXXXXXXXXXXXXXX",
      "subnetwork_name": "swp-subnet"
    },
    "connection": {
      "src_ip": "192.168.10.2",
      "src_port": 48640,
      "dest_port": 8888,
      "dest_ip": "10.10.10.5",
      "protocol": 6
    }
  },
  "resource": {
    "type": "gce_subnetwork",
    "labels": {
      "subnetwork_id": "7147084067647653041",
      "project_id": "XXXXXXXXXXXXXX",
      "location": "us-central1",
      "subnetwork_name": "intf-subnet"
    }
  },
  "timestamp": "2025-12-30T12:51:36.628538815Z",
  "logName": "projects/dec30-run1-agent/logs/compute.googleapis.com%2Ffirewall",
  "receiveTimestamp": "2025-12-30T12:51:40.846652708Z"
}

14. Temizleme

JupyterLab not defterinizde yeni bir hücre oluşturun ve Agent Engine dağıtımının silinmesini tetikleyecek aşağıdaki kodu çalıştırın.

"project number" ve "reasoningEngines token" güncellediğinizden emin olun.

import requests
token = !gcloud auth application-default print-access-token
ENDPOINT = "https://us-central1-aiplatform.googleapis.com"
response = requests.delete(
    f"{ENDPOINT}/v1beta1/projects/218166745590/locations/us-central1/reasoningEngines/3086854705725308928",
    params={"force": "true"},
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {token[0]}"
    },
)
print(response.text)

Cloud Shell'den eğitim bileşenlerini silin.

gcloud workbench instances delete workbench-tutorial --project=$projectid --location=us-central1-a

gcloud network-security gateway-security-policies rules delete allow-notebook-subnet \
    --gateway-security-policy=my-swp-policy \
    --location=us-central1

gcloud network-security gateway-security-policies rules delete allow-example \
    --gateway-security-policy=my-swp-policy \
    --location=us-central1

gcloud network-security gateway-security-policies delete my-swp-policy \
    --location=us-central1
gcloud network-services gateways delete my-swp-instance\
    --location=us-central1

gcloud dns record-sets delete swp.demo.com --zone=private-dns-codelab  --type=A

gcloud dns managed-zones delete private-dns-codelab


gcloud compute network-attachments delete psc-network-attachment --region=us-central1 --quiet

export ROUTER_NAME=$(gcloud compute routers list --regions=us-central1 \
    --filter="name ~ swg-autogen-router" --format="value(name)")


 gcloud compute routers nats delete swg-autogen-nat --router=$ROUTER_NAME --region=us-central1 --quiet 

gcloud compute routers delete $ROUTER_NAME --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet rfc1918-subnet1 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet swp-subnet
 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet intf-subnet --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet proxy-subnet
 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet notebook-subnet
--region=us-central1 --quiet

gcloud compute networks delete consumer-vpc --quiet

15. Tebrikler

Tebrikler! İnternet çıkışı açık bir proxy üzerinden gerçekleştirilen Private Service Connect arayüzü ile dağıtılan Agent Engine'i başarıyla yapılandırdınız ve doğruladınız.

Tüketici altyapısını oluşturdunuz ve üreticinin tüketici ile üretici arasındaki iletişimi köprülemek için çoklu NIC VM oluşturmasına olanak tanıyan bir ağ eki eklediniz. İnternet bağlantısına izin veren açık proxy ve DNS eşlemesi oluşturmayı öğrendiniz.

Cosmopup, eğitici içeriklerin harika olduğunu düşünüyor.

e6d3675ca7c6911f.jpeg

Yapabilecekleriniz

Daha fazla bilgi ve videolar

Referans belgeler