Integrasi PSC SWP Agent Engine (ADK)

1. Pengantar

Antarmuka Private Service Connect adalah resource yang memungkinkan jaringan Virtual Private Cloud (VPC) produsen memulai koneksi ke berbagai tujuan dalam jaringan VPC konsumen. Jaringan produsen dan konsumen dapat berada dalam project dan organisasi yang berbeda.

Jika lampiran jaringan menerima koneksi dari antarmuka Private Service Connect, Google Cloud akan mengalokasikan alamat IP ke antarmuka dari subnet konsumen yang ditentukan oleh lampiran jaringan. Jaringan konsumen dan produsen terhubung dan dapat berkomunikasi menggunakan alamat IP internal.

Koneksi antara lampiran jaringan dan antarmuka Private Service Connect mirip dengan koneksi antara endpoint Private Service Connect dan lampiran layanan, tetapi memiliki dua perbedaan utama:

  • Lampiran jaringan memungkinkan jaringan produsen memulai koneksi ke jaringan konsumen (traffic keluar layanan terkelola), sedangkan endpoint memungkinkan jaringan konsumen memulai koneksi ke jaringan produsen (traffic masuk layanan terkelola).
  • Koneksi antarmuka Private Service Connect bersifat transitif. Artinya, jaringan produsen dapat berkomunikasi dengan jaringan lain yang terhubung ke jaringan konsumen.

Pertimbangan aksesibilitas Antarmuka PSC Vertex AI

  • PSC-Interface dapat merutekan traffic ke tujuan berbasis VPC atau lokal yang dipelajari oleh jaringan VPC.
  • Untuk membatasi cakupan jangkauan dari lampiran jaringan yang digunakan oleh Agent Engine ke jaringan VPC, penerapan aturan firewall keluar adalah praktik terbaiknya.
  • Untuk membatasi cakupan traffic keluar jaringan yang berasal dari subnet lampiran jaringan Agent Engine, aturan firewall keluar VPC harus di-deploy. Aturan ini akan secara eksplisit mengizinkan traffic dari Agent Engine ke SWP, sekaligus menolak semua traffic keluar lainnya.

Pertimbangan VPC-SC Antarmuka PSC Vertex AI

  • Anda harus menyediakan konektivitas keluar internet dalam VPC pelanggan agar PSC-Interface Agent Engine berfungsi, meskipun Kontrol Layanan VPC diaktifkan.

Secure Web Proxy

Secure Web Proxy adalah layanan terkelola berbasis cloud yang memberi Anda kontrol dan keamanan terperinci untuk traffic keluar (HTTP/HTTPS). Layanan ini berfungsi sebagai gateway pusat, yang memungkinkan Anda menerapkan kebijakan keamanan pada koneksi yang dimulai dari Agent Engine yang di-deploy dengan Antarmuka PSC ke resource VPC, seperti VM, GKE, internet, dan lingkungan multicloud.

Masalah yang Dipecahkan

  • Mencegah pemindahan data yang tidak sah: Memblokir upload atau komunikasi yang tidak sah dengan situs berbahaya.
  • Menerapkan kepatuhan: Memastikan traffic keluar mematuhi kebijakan keamanan dan penanganan data organisasi Anda.
  • Mengurangi biaya operasional: Sebagai layanan terkelola sepenuhnya, Secure Web Proxy tidak mengharuskan Anda men-deploy, menskalakan, atau memelihara VM proxy Anda sendiri.
  • Memberikan visibilitas mendalam: Memungkinkan pemeriksaan traffic yang dienkripsi Transport Layer Security (TLS) untuk mendeteksi ancaman tersembunyi.

Untuk informasi tambahan, lihat referensi berikut:

Men-deploy agen | AI Generatif di Vertex AI | Google Cloud

Menyiapkan antarmuka Private Service Connect untuk resource Vertex AI | Google Cloud

Yang akan Anda build

Dalam tutorial ini, Anda akan membuat Agent Engine komprehensif yang di-deploy dengan Antarmuka Private Service Connect (PSC) yang terintegrasi dengan SWP untuk melakukan hal berikut menggunakan library ADK:

  • Deploy peering DNS di Agent Engine untuk me-resolve Nama Domain yang Sepenuhnya Memenuhi Syarat SWP yang digunakan dalam konfigurasi proxy.
  • Izinkan konektivitas ke situs publik (https://api.frankfurter.app/) melalui Secure Web Proxy yang di-deploy di VPC konsumen dengan alamat RFC1918.
  • Izinkan traffic dari Subnet Lampiran Jaringan ke SWP sambil menolak yang lainnya.

Gambar 1

565e9eb07ef18f44.png

Yang akan Anda pelajari

  • Cara membuat lampiran jaringan
  • Cara produsen dapat menggunakan lampiran jaringan untuk membuat antarmuka PSC
  • Cara membuat komunikasi dari produsen ke konsumen menggunakan Peering DNS
  • Cara men-deploy dan menggunakan SWP untuk traffic keluar internet
  • Cara menentukan aturan firewall keluar untuk mengurangi jangkauan jaringan Agent Engine

Yang Anda butuhkan

Project Google Cloud

Izin IAM

2. Sebelum memulai

Mengupdate project untuk mendukung tutorial

Tutorial ini menggunakan $variables untuk membantu penerapan konfigurasi gcloud di Cloud Shell.

Di dalam Cloud Shell, lakukan hal berikut:

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

Pengaktifan API

Di dalam Cloud Shell, lakukan hal berikut:

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"

Memverifikasi bahwa API berhasil diaktifkan

gcloud services list --enabled

3. Penyiapan Konsumen

Buat VPC Konsumen

VPC ini berada di project pelanggan. Resource berikut akan dibuat di VPC ini

  • Subnet Konsumen
  • Subnet Lampiran Jaringan
  • Subnet khusus proxy
  • Aturan Firewall
  • Cloud DNS

Di dalam Cloud Shell, lakukan hal berikut:

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

Buat subnet konsumen

Di dalam Cloud Shell, buat subnet untuk SWP:

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

Buat subnet Lampiran Jaringan Private Service Connect

Di dalam Cloud Shell, buat subnet untuk PSC Network Attachment:

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

Buat subnet proxy regional

Di dalam Cloud Shell, buat subnet khusus proxy yang diperlukan untuk produk berbasis Envoy seperti Secure Web Proxy dan Load Balancer Aplikasi Internal/Eksternal Regional. Flag –purpose harus ditetapkan ke REGIONAL_MANAGED_PROXY:

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

Buat subnet notebook

Di dalam Cloud Shell, buat subnet untuk instance notebook:

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. Membuat Secure Web Proxy

Mode Eksplisit Secure Web Proxy (atau Mode Perutean Proxy Eksplisit) adalah metode deployment yang mengharuskan beban kerja klien dikonfigurasi secara eksplisit untuk menggunakan alamat IP internal atau Nama Domain yang Sepenuhnya Memenuhi Syarat dan port SWP sebagai proxy penerusan.

Kebijakan ini akan berisi aturan yang mengatur traffic melalui Secure web proxy berdasarkan kecocokan sesi, host() == 'api.frankfurter.app' & kecocokan aplikasi request.method == 'GET'

Pada langkah-langkah di bawah, pastikan untuk mengubah YOUR-PROJECT-ID menjadi Project ID Anda

Di dalam Cloud Shell, buat file policy.yaml:

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

Di dalam Cloud Shell, impor kebijakan:

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

Membuat Aturan Secure Web Proxy

Tentukan aturan dalam kebijakan untuk menentukan traffic mana yang diizinkan atau ditolak. Aturan dievaluasi berdasarkan prioritas.

Di dalam Cloud Shell, Buat file rule.yaml untuk mengizinkan akses ke endpoint internet yang digunakan oleh mesin agen, api.frankfurter.app:

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

Di Cloud Shell, buat aturan kebijakan keamanan:

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

Membuat Aturan Secure Web Proxy

Instance SWP, yang di-deploy dalam mode perutean eksplisit, harus dibuat sehingga Agent Engine diperlukan untuk menentukan alamat IP atau FQDN SWP dalam konfigurasi proxy ADK, seperti yang ditentukan dalam file YAML gateway. Konfigurasi ini juga menautkan instance ke kebijakan, jaringan, dan subnet yang sesuai.

Di dalam Cloud Shell, Buat file gateway.yaml yang digunakan untuk men-deploy SWP.

Pastikan untuk menyimpan file YAML setelah memperbarui variabel berikut dengan detail lingkungan Anda: PROJECT_ID, REGION, NETWORK_NAME, dan PROXY_ONLY_SUBNET_NAME. Port 8888 yang ditentukan adalah port tunnel luar yang dipetakan ke konfigurasi proxy dalam Agent Engine.

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

Di dalam Cloud Shell, impor gateway:

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

5. Lampiran jaringan Private Service Connect

Lampiran jaringan adalah resource regional yang mewakili sisi konsumen antarmuka Private Service Connect. Anda mengaitkan satu subnet dengan lampiran jaringan, dan produsen akan menetapkan IP ke antarmuka Private Service Connect dari subnet tersebut. Subnet harus berada di region yang sama dengan lampiran jaringan. Lampiran jaringan harus berada di region yang sama dengan layanan produsen.

Buat lampiran jaringan

Di dalam Cloud Shell, buat lampiran jaringan.

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

Mencantumkan lampiran jaringan

Di dalam Cloud Shell, cantumkan lampiran jaringan.

gcloud compute network-attachments list

Mendeskripsikan lampiran jaringan

Di dalam Cloud Shell, deskripsikan lampiran jaringan.

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

Catat nama Lampiran Jaringan PSC, psc-network-attachment, yang akan digunakan oleh produsen saat membuat Antarmuka Private Service Connect.

Untuk melihat URL Lampiran Jaringan PSC di Konsol Cloud, buka:

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

15f80b46c3a0332d.png

6. Zona DNS Pribadi

Anda akan membuat Zona Cloud DNS untuk demo.com dan mengisinya dengan data A yang mengarah ke alamat IP SWP Anda. Selanjutnya, peering DNS akan di-deploy di Agent Engine, yang akan memungkinkan akses ke data DNS konsumen.

Di dalam Cloud Shell, lakukan langkah-langkah berikut yang membuat nama DNS demo.com.

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"

Dapatkan dan simpan Alamat IP SWP yang digunakan untuk data DNS A.

Di dalam Cloud Shell, lakukan deskripsi terhadap swp, my-swp-instance:

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

Di dalam Cloud Shell, buat set data untuk SWP, swp.demo.com, pastikan untuk memperbarui Alamat IP berdasarkan output lingkungan Anda.

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

Konfigurasi Firewall

Buat aturan Cloud Firewall untuk mengizinkan akses dari Antarmuka PSC

Di bagian berikut, buat aturan firewall yang mengizinkan traffic yang berasal dari akses Lampiran Jaringan PSC ke subnet SWP di VPC Konsumen. Untuk meningkatkan keamanan, Anda dapat menentukan Alamat IP SWP sebagai satu-satunya tujuan.

Di Cloud Shell, buat aturan firewall keluar yang mengizinkan akses dari lampiran jaringan ke SWP:

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

Di Cloud Shell, buat aturan firewall keluar yang menolak semua traffic dari lampiran jaringan:

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. Buat Kebijakan Firewall ke Jaringan VPC untuk memastikan Threat Intelligence:

Di bagian berikut, buat kebijakan firewall yang memungkinkan Anda memanfaatkan daftar ancaman terkelola Google untuk memblokir situs berbahaya yang diketahui sebelum traffic diterima oleh SWP.

Di Cloud Shell, buat kebijakan firewall global:

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

Di Cloud Shell, kaitkan Kebijakan dengan VPC Anda:

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

Di Cloud Shell, tambahkan Aturan Threat Intelligence:

Aturan ini akan menghentikan traffic ke pihak berbahaya yang diketahui sebelum memulai traffic dari Agen. Dalam contoh ini, kami menambahkan aturan untuk Memblokir Node Keluar Tor (Keluar), dan Memblokir IP Berbahaya yang Diketahui (Keluar), Memblokir Proxy Anonim yang Diketahui(Keluar), Memblokir Penambang Kripto untuk mencegah penggunaan resource yang tidak sah (Keluar),

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. Membuat Notebook Jupyter

Bagian berikut akan memandu Anda membuat Notebook Jupyter. Notebook ini akan digunakan untuk men-deploy Agent Engine yang menargetkan proxy eksplisit untuk Egress Internet.

Membuat akun layanan yang dikelola pengguna

Di bagian berikut, Anda akan membuat akun layanan yang akan dikaitkan dengan instance Vertex AI Workbench yang digunakan dalam tutorial.

Dalam tutorial ini, akun layanan akan memiliki peran berikut yang diterapkan:

Di dalam Cloud Shell, buat akun layanan.

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

Di dalam Cloud Shell, perbarui akun layanan dengan peran Storage Admin.

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

Di dalam Cloud Shell, perbarui akun layanan dengan peran Vertex AI User.

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

Di dalam Cloud Shell, perbarui akun layanan dengan peran Artifact Registry Admin.

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

Di dalam Cloud Shell, izinkan akun layanan notebook menggunakan akun layanan default Compute Engine.

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. Membuat Instance Vertex AI Workbench

Di bagian berikut, buat instance Vertex AI Workbench yang menggabungkan akun layanan yang dibuat sebelumnya, notebook-sa.

Di dalam Cloud Shell, buat instance private-client.

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

Tambahkan aturan lain di Secure Web Proxy yang ada untuk meneruskan traffic dari instance notebook ini:

Di Cloud Shell, buat file rule-notebook.yaml menggunakan editor teks, pastikan untuk memperbarui YAML dengan Project ID Anda

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

Di Cloud Shell, buat aturan kebijakan keamanan:

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. Pembaruan Agen Layanan Vertex AI

Vertex AI bertindak atas nama Anda untuk melakukan operasi seperti mendapatkan Alamat IP dari subnet PSC Network Attachment yang digunakan untuk membuat Antarmuka PSC. Untuk melakukannya, Vertex AI menggunakan agen layanan (tercantum di bawah) yang memerlukan izin Network Admin:

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

Di dalam Cloud Shell, dapatkan nomor project Anda.

gcloud projects describe $projectid | grep projectNumber

Di dalam Cloud Shell, tetapkan nomor project Anda.

projectnumber=YOUR-PROJECT-NUMBER

Di dalam Cloud Shell, buat akun layanan untuk AI Platform. Lewati langkah ini jika Anda sudah memiliki akun layanan di project Anda.

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

Di dalam Cloud Shell, perbarui akun agen layanan dengan peran compute.networkAdmin.

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

Di dalam Cloud Shell, perbarui akun agen layanan dengan peran dns.peer

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

Pembaruan Akun Layanan Default

Beri akun layanan default Anda akses ke Vertex AI. Perhatikan bahwa mungkin perlu beberapa saat agar perubahan akses diterapkan.

Di dalam Cloud Shell, perbarui akun layanan default dengan peran aiplatform.user

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

11. Men-deploy Agent Engine

Catatan: Kita akan menggunakan konsol GCP dan notebook JupyterLab untuk menyelesaikan tugas di bagian ini

Di bagian berikut, Anda akan membuat notebook yang melakukan tugas berikut:

  • Menggunakan Frankfurter API (https://api.frankfurter.app/) untuk mendapatkan data nilai tukar
  • Merujuk ke proxy eksplisit (proxy_server) yang menargetkan SWP di VPC konsumen menggunakan FQDN swp.demo.com
  • Tentukan dnsPeeringConfigs "domain": "demo.com."

Jalankan tugas pelatihan di instance Vertex AI Workbench.

  • Di konsol Google Cloud, buka Vertex AI → Workbench
  • Di samping nama instance Vertex AI Workbench Anda (workbench-tutorial), klik Open JupyterLab. Instance Vertex AI Workbench Anda akan terbuka di JupyterLab.
  • Pilih File > New > Notebook
  • Pilih Kernel > Python 3

Instal library Python yang diperlukan: Instal library yang diperlukan untuk Agent Engine, termasuk pyyaml, google-cloud-aiplatform, cloudpickle, google-cloud-api-keys, dan langchain-google-vertexai.

Di notebook JupyterLab, buat sel baru dan jalankan perintah berikut dengan menentukan alamat IP SWP

7b827a6a38bb5afc.png

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

Tentukan variabel berikut berdasarkan lingkungan Anda dalam cuplikan kode berikut:

  • PROJECT_ID
  • BUCKET_NAME
  • AGENT_NAME

Di lab ini, Anda akan menggunakan variabel BUCKET_NAME dan AGENT_NAME untuk menginisialisasi dan mengonfigurasi bucket penyimpanan yang tersedia secara global

Di bagian berikut, PROXY_SERVER ditentukan, misalnya swp.demo.com yang memerlukan peering DNS untuk resolusi nama. Dalam konfigurasi, AGENT_PEER_DOMAIN di-deploy sebagai demo.com. yang sesuai dengan zona DNS pribadi yang dibuat pada langkah sebelumnya dalam AGENT_PEER_NETWORK, consumer-vpc.

Di notebook JupyterLab, buat sel baru dan jalankan perintah berikut:

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

Di notebook JupyterLab, buat sel baru, lalu jalankan kode berikut.

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

Di notebook JupyterLab, buat sel baru, lalu jalankan perintah berikut untuk membuat variabel proxy yang sesuai dengan FQDN dan port SWP.

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

Sel kode berikut menunjukkan konfigurasi proxy eksplisit untuk Agent Engine dalam mengakses endpoint internet api.frankfurter.app dengan menentukan SWP, menggunakan PROXY_SERVER_TO_USE yang dipetakan ke os.environ["PROXY_SERVER_URL"].

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

Di notebook JupyterLab, buat sel baru dan jalankan kode berikut yang menentukan penerapan alat untuk menargetkan API pertukaran mata uang di 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],
)

Di notebook JupyterLab, buat sel baru dan jalankan kode berikut.

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

Di notebook JupyterLab, buat sel baru dan jalankan perintah berikut yang memanggil konfigurasi antarmuka PSC yang digunakan oleh Agent Engine, selain peering DNS.

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

Di notebook JupyterLab, buat sel baru dan jalankan kode berikut.

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

Di notebook JupyterLab, buat sel baru dan jalankan kode berikut.

%%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

Di notebook JupyterLab, buat sel baru dan jalankan perintah berikut yang membuat Agen.

!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

ID mesin penalaran akan dibuat saat eksekusi sel. Untuk langkah berikutnya, Anda akan memerlukan ID yang dibuat, yaitu 3235268984265768960 dalam contoh ini.

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

Di notebook JupyterLab, buat sel baru dan jalankan perintah berikut, pastikan untuk memperbarui dengan Nomor Project dan ID penalaran Agent Engine dari output sebelumnya:

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

Di notebook JupyterLab, buat sel baru dan jalankan kode berikut.

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)

Contoh eksekusi yang berhasil yang memvalidasi konektivitas ke endpoint publik api.frankfurther.app melalui SWP berdasarkan rasio konversi USD ke INR.

f9f925983ab5cc9d.png

12. Validasi Antarmuka PSC

Anda juga dapat melihat IP Network Attachment yang digunakan oleh Agent Engine dengan membuka:

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

Pilih project tenant (nama project yang diakhiri dengan -tp)

c9c412334a7f5ad9.png

Kolom yang ditandai menunjukkan alamat IP yang digunakan oleh Agent Engine dari PSC Network Attachment.

e94c6c03fb51f7fe.png

13. SWP - Validasi Cloud Logging

Anda dapat melihat Cloud Logging untuk memvalidasi keluar internet yang dilakukan oleh SWP, buka:

Monitoring → Logs Explorer

Masukkan kueri: resource.type=" networkservices.googleapis.com/Gateway", lalu Klik Run Query. Berikut adalah contoh yang mengonfirmasi endpoint tujuan, api.frankfurter.app.

f53831ef8ec663db.png

fc154a5b22da2a87.png

Contoh Cloud Logging berikut memvalidasi hal berikut:

Destination_range: Alamat IP Antarmuka PSC Agent Engine

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

Pastikan untuk mengubah project_id untuk kueri cloud logging.

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. Pembersihan

Di notebook JupyterLab, buat sel baru dan jalankan perintah berikut yang akan memicu penghapusan deployment Agent Engine.

Pastikan Anda memperbarui "project number" dan "reasoningEngines token"

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)

Dari Cloud Shell, hapus komponen tutorial.

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. Selamat

Selamat, Anda telah berhasil mengonfigurasi dan memvalidasi Agent Engine yang di-deploy dengan Antarmuka Private Service Connect dengan egress internet yang dilakukan melalui proxy eksplisit.

Anda telah membuat infrastruktur konsumen, dan menambahkan lampiran jaringan yang memungkinkan produsen membuat VM multi-NIC untuk menjembatani komunikasi konsumen dan produsen. Anda telah mempelajari cara membuat peering DNS dan proxy eksplisit yang memungkinkan konektivitas Internet.

Cosmopup menganggap tutorial itu luar biasa!!

e6d3675ca7c6911f.jpeg

Apa selanjutnya?

Bacaan lebih lanjut & Video

Dokumen referensi