Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Men-deploy agen dan Agent Gateway dengan Kontrol Layanan VPC

1. Pengantar

Codelab ini memandu Anda mengonfigurasi lingkungan Google Cloud untuk menyiapkan agen dan Agent Gateway dengan perimeter Kontrol Layanan VPC. Anda akan membuat perimeter Kontrol Layanan VPC, mengonfigurasi jaringan dan DNS, men-deploy Agent Gateway dengan otorisasi permintaan Identity-Aware Proxy (IAP), dan menguji agen secara aman.

Yang akan Anda build

Dalam codelab ini, Anda akan membangun arsitektur Google Cloud yang aman untuk Gemini Enterprise Agent Platform dan Agent Gateway yang melakukan hal berikut:

Menggunakan Kontrol Layanan VPC untuk membantu mengamankan resource project dari pemindahan data yang tidak sah.
Mengonfigurasi Akses Google Pribadi, Private Service Connect (PSC), dan zona pribadi Cloud DNS untuk perutean API pribadi.
Menyediakan Agent Gateway dengan proxy traffic terpusat, aturan keluar, dan konfigurasi protokol.
Menerapkan kebijakan otorisasi permintaan Identity-Aware Proxy (IAP).
Men-deploy dan menguji agen Agent Engine dengan aman melalui konektivitas pribadi.

Yang akan Anda pelajari

Cara mengaktifkan Google Cloud API yang diperlukan untuk Agent Platform dan keamanan.
Cara mengonfigurasi perimeter Kontrol Layanan VPC dan aturan akses ingress.
Cara menyiapkan konektivitas jaringan pribadi dan data DNS Pribadi.
Cara membuat Agent Gateway dan template konektivitas agen.
Cara mengonfigurasi ekstensi dan kebijakan otorisasi permintaan IAP.
Cara men-deploy dan menguji agen Agent Engine secara aman.

Yang Anda butuhkan

Google Cloud CLI diinstal dan diupdate ke versi terbaru.
Python 3 diinstal di workstation Anda.
Git diinstal di workstation Anda.
Izin akun penagihan dan Organisasi Google Cloud yang aktif.

2. Prasyarat

Bagian ini menguraikan persyaratan alat command line dasar dan konfigurasi lingkungan yang diperlukan sebelum menjalankan skrip penyiapan.

Pastikan Google Cloud CLI telah diinstal dan diupdate ke versi terbaru, lalu lakukan autentikasi dengan Akun Google Anda. Update komponen Google Cloud CLI Anda untuk memastikan Anda memiliki dukungan fitur terbaru untuk Layanan Jaringan dan Kontrol Layanan VPC.

gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL

Pastikan Python 3 telah diinstal untuk mengonfigurasi dan men-deploy framework agen kustom. Untuk mengetahui petunjuknya, lihat Menginstal modul Python:

python3 --version

Pastikan Git diinstal untuk meng-clone repositori contoh yang berisi kode penyiapan dan template konfigurasi. Untuk mengetahui petunjuknya, lihat Penginstalan Git.

3. Mengonfigurasi project Google Cloud

Membuat project terisolasi dalam organisasi Anda memastikan semua resource, jaringan, dan izin yang digunakan dalam codelab ini tetap dienkapsulasi dan dapat dikelola. Pelajari lebih lanjut cara Membuat dan Mengelola Project.

Lakukan inisialisasi project Google Cloud baru di organisasi Anda untuk menghosting resource penyiapan ini. Anda juga dapat menggunakan project Anda sendiri:

export PROJ_ID="YOUR_PROJECT_ID"
gcloud projects create ${PROJ_ID} --organization=YOUR_ORG_ID

gcloud config set project $PROJ_ID

gcloud auth application-default set-quota-project $PROJ_ID

Dapatkan kredensial default aplikasi dengan login:

gcloud auth application-default login

Verifikasi konfigurasi Anda:

gcloud config list

Aktifkan penagihan

Tautkan akun penagihan yang aktif ke project yang baru dibuat untuk mengaktifkan penggunaan layanan.

Mengaktifkan penagihan adalah prasyarat untuk menggunakan kuota API dan menyediakan infrastruktur Google Cloud seperti Agent Gateway, virtual private cloud, dan node komputasi. Untuk mengetahui detail tentang konfigurasi penagihan, lihat Dokumentasi Penagihan Google Cloud.

gcloud billing accounts list
# Copy the billing account to assign to your GCP project
gcloud billing projects link $PROJ_ID --billing-account=BILLING_ACCOUNT_ID

4. Aktifkan Layanan

Aktifkan semua Google Cloud API yang diperlukan untuk fitur Agen, Gateway Agen, jaringan, keamanan, dan kemampuan observasi.

Pengaktifan API mengekspos layanan cloud backend untuk pengelolaan resource, kemampuan observasi, dan kemampuan jaringan yang diperlukan untuk konektivitas agen yang aman. Pelajari lebih lanjut di Dokumentasi Service Usage API.

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 \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com \
  securitycenter.googleapis.com

gcloud services enable \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com \
  accesscontextmanager.googleapis.com \
  discoveryengine.googleapis.com \
  agentidentity.googleapis.com \
  agentidentitycredentials.googleapis.com

5. Mengekspor Variabel Lingkungan

Tentukan variabel lingkungan yang dapat digunakan kembali untuk region, project ID, nomor project, ID organisasi, dan identitas pengguna. Menetapkan variabel shell menstandardisasi perintah konfigurasi resource di seluruh langkah, sehingga meminimalkan kesalahan penggantian manual selama eksekusi skrip.

export REGION="us-central1"
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)

6. Membuat Perimeter Kontrol Layanan VPC

Buat perimeter Kontrol Layanan VPC untuk mengisolasi resource project Anda dan membantu mencegah pemindahan data yang tidak sah. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Kontrol Layanan VPC.

Mengambil kebijakan akses Anda

Ambil ID kebijakan Access Context Manager yang terkait dengan organisasi Anda. Kebijakan Access Context Manager menentukan batas organisasi tempat perimeter Kontrol Layanan VPC dilampirkan dan diterapkan.

gcloud access-context-manager policies list --organization=$ORG_ID

Mengekspor kebijakan akses Anda

Tetapkan kebijakan akses dalam konfigurasi gcloud CLI Anda dan kumpulkan daftar layanan terbatas yang didukung. Mengumpulkan semua layanan yang didukung memungkinkan Anda membuat set aturan perimeter terbatas yang mencegah akses tidak sah di seluruh endpoint Google Cloud API.

export ACCESS_POLICY=ACCESS_POLICY_ID

gcloud config set access_context_manager/policy $ACCESS_POLICY
SUPPORTED_SERVICES=$(gcloud access-context-manager supported-services list --format="value(name)" | paste -sd, -)

Membuat perimeter

Tentukan nama perimeter layanan dan terapkan batasan di seluruh layanan Google Cloud yang didukung dalam project. Perimeter bertindak sebagai batas yang mengelilingi resource project, membatasi traffic masuk dan keluar langsung kecuali jika diizinkan secara eksplisit oleh aturan masuk/keluar.

export PERIMETER_NAME="perimeter_${PROJ_NO}"

gcloud access-context-manager perimeters create accessPolicies/${ACCESS_POLICY}/servicePerimeters/${PERIMETER_NAME} \
--title="${PERIMETER_NAME}" \
--perimeter-type=regular \
--resources=projects/${PROJ_NO} \
--restricted-services=${SUPPORTED_SERVICES}

Membuat kebijakan ingress

Kebijakan ingress menentukan kondisi eksplisit—seperti identitas pengguna atau tingkat akses tertentu—yang memungkinkan traffic berasal dari luar perimeter dan diizinkan untuk menjangkau resource terbatas di dalamnya.

Buat file YAML yang mengizinkan akses eksplisit untuk identitas pengguna Anda di semua layanan:

cat > ingress-policy.yaml << EOF
- ingressFrom:
    identities:
      - user:${USER_IDENTITY}
    sources:
      - accessLevel: '*'
  ingressTo:
    operations:
      - serviceName: '*'
    resources:
      - '*'
EOF

gcloud access-context-manager perimeters update $PERIMETER_NAME --set-ingress-policies="ingress-policy.yaml"

Codelab ini mengonfigurasi lingkungan Anda untuk menghindari penolakan akses Kontrol Layanan VPC secara default. Namun, untuk membantu Anda memecahkan masalah selama pengujian, Kontrol Layanan VPC menyediakan log penolakan mendetail dan alat analisis kebijakan.

Memecahkan masalah penolakan Kontrol Layanan VPC

Selama pengujian, lihat tips pemecahan masalah berikut:

Aktifkan Dasbor Pelanggaran untuk melacak pelanggaran terbaru di lingkungan Anda.
Pantau Cloud Audit Logs untuk log penolakan akses (403) Kontrol Layanan VPC.
Mendiagnosis pelanggaran menggunakan ID unik atau token pelanggaran di Penganalisis Pelanggaran.
Tonton video Pemecahan masalah Kontrol Layanan VPC untuk mengetahui panduan mendetail.

7. Menyiapkan jaringan

Konfigurasi setelan jaringan VPC untuk mendukung komunikasi pribadi dengan Google API dan layanan Google. Konfigurasi jaringan yang tepat menjamin bahwa traffic jaringan antara agen, gateway, dan Google Cloud API tetap berada di jaringan internal pribadi. Untuk mengetahui pola jaringan yang mendetail, lihat Dokumentasi VPC Google Cloud.

Mengaktifkan Akses Google Pribadi

Aktifkan Akses Google Pribadi di subnet default sehingga instance VM dan workload internal dapat menjangkau Google API menggunakan alamat IP internal, bukan alamat IP publik.

export NETWORK_NAME="default"
export SUBNET_NAME="default"

gcloud compute networks subnets update $SUBNET_NAME --region=$REGION --enable-private-ip-google-access

Membuat lampiran jaringan PSC

Buat lampiran jaringan Private Service Connect (PSC) untuk konektivitas Agent Gateway. Lampiran jaringan menyediakan antarmuka Private Service Connect (PSC), yang memfasilitasi komunikasi lintas-VPC yang aman antara layanan Agent Gateway dan subnet internal Anda.

gcloud compute network-attachments create psc-agw-${REGION} \
  --region=${REGION} \
  --subnets=${SUBNET_NAME} \
  --connection-preference=ACCEPT_AUTOMATIC

Verifikasi

Ambil dan periksa URI resource link mandiri dari lampiran jaringan yang baru dibuat. Memvalidasi URI resource memastikan network attachment berhasil di-instantiate dan dapat dirujuk dalam template konektivitas.

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

Membuat zona pribadi Cloud DNS

Konfigurasi zona pribadi Cloud DNS untuk merutekan traffic googleapis.com melalui rentang IP pribadi. Zona DNS pribadi menggantikan pencarian domain publik untuk googleapis.com, mengarahkan semua traffic keluar ke IP Virtual (VIP) internal pribadi dalam jaringan VPC Anda. Lihat Zona Pribadi Cloud DNS untuk mengetahui detail selengkapnya.

export ZONE_NAME="gapis"

gcloud dns managed-zones create ${ZONE_NAME} \
--visibility=private \
--networks=https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/global/networks/${NETWORK_NAME} \
  --description="Privately reach Google APIs" \
  --dns-name=googleapis.com

gcloud dns record-sets transaction start --zone=${ZONE_NAME}

Pilih salah satu opsi domain berikut untuk perutean pribadi (jalankan hanya perintah di bagian Opsi 1 atau Opsi 2 sebelum mengeksekusi transaksi) — baca selengkapnya di Opsi konfigurasi Akses Google Pribadi:

Opsi 1: VIP Pribadi [Direkomendasikan]

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME private.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=private.googleapis.com. \
    --type=A 199.36.153.8 199.36.153.9 199.36.153.10 199.36.153.11 \
    --zone=${ZONE_NAME} \
    --ttl=300

Opsi 2: VIP terbatas

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME restricted.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=restricted.googleapis.com. \
    --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
    --zone=${ZONE_NAME} \
    --ttl=300

Lakukan transaksi DNS:

gcloud dns record-sets transaction execute --zone=${ZONE_NAME}

8. Buat Agent Gateway

Sediakan Agent Gateway dan tentukan template konektivitas serta aturan peruteannya. Agent Gateway berfungsi sebagai proxy terpusat untuk mengelola traffic agen, kebijakan keluar, penanganan protokol, dan penemuan layanan yang aman. Untuk referensi arsitektur, lihat Ringkasan Agent Gateway.

Diagram arsitektur yang menampilkan permintaan pemilihan rute Agen melalui Agent Gateway, otorisasi permintaan IAP, dan lampiran jaringan PSC di dalam perimeter Kontrol Layanan VPC.

export AGW_NAME="gateway-${USER_IDENTITY}"
export AGW_CONNECTIVITY_TEMPLATE="agw-connectivity-template-${USER_IDENTITY}"

Membuat Template Konektivitas Agen

Template konektivitas menentukan konfigurasi jaringan, kebijakan pemilihan rute keluar, setelan peering DNS, dan URI lampiran jaringan yang diperlukan oleh gateway untuk menangani permintaan keluar.

cat > ${AGW_CONNECTIVITY_TEMPLATE}.yaml << EOF
name: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
  networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domain: googleapis.com.
    targetNetwork: projects/${PROJ_ID}/global/networks/${NETWORK_NAME}
  vpcEgress: ALL_TRAFFIC
EOF

gcloud network-services agent-connectivity-templates import ${AGW_CONNECTIVITY_TEMPLATE} \
    --source="${AGW_CONNECTIVITY_TEMPLATE}.yaml" \
    --location=${REGION}

Buat Agent Gateway

cat > ${AGW_NAME}-config.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
registries:
  - //agentregistry.googleapis.com/projects/${PROJ_NO}/locations/global
EOF

gcloud network-services agent-gateways import ${AGW_NAME} \
    --source="${AGW_NAME}-config.yaml" \
    --location=${REGION}

Memverifikasi kreasi

Pastikan resource Agent Gateway berhasil di-deploy dan dikonfigurasi. Mendeskripsikan gateway agen yang di-deploy akan mengonfirmasi bahwa status operasionalnya aktif dan memverifikasi bahwa template dan registry konektivitas terkait terpasang dengan benar.

gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

9. Membuat Otorisasi melalui IAP

Konfigurasi kebijakan otorisasi permintaan Identity-Aware Proxy (IAP) dan ekstensi layanan untuk memverifikasi kredensial permintaan sebelum memberikan akses ke Agent Gateway. Untuk mengetahui informasi selengkapnya, lihat dokumentasi IAP.

Diagram alur yang menunjukkan cara Agent Gateway mendelegasikan otorisasi permintaan ke Identity-Aware Proxy (IAP) menggunakan Kebijakan Authz Network Security dan Ekstensi Layanan Authz.

export AUTHZ_EXT="iap-authz-extension-${USER_IDENTITY}"
export AUTHZ_POLICY="iap-authz-policy-${USER_IDENTITY}"

Membuat Ekstensi AuthZ

cat > ${AUTHZ_EXT}.yaml << EOF
name: ${AUTHZ_EXT}
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
EOF

gcloud service-extensions authz-extensions import ${AUTHZ_EXT} \
    --source=${AUTHZ_EXT}.yaml \
    --location=${REGION}

Buat Kebijakan AuthZ dan ikat ke Agent Gateway

cat > ${AUTHZ_POLICY}.yaml << EOF
name: ${AUTHZ_POLICY}
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AUTHZ_EXT}"
EOF

gcloud network-security authz-policies import ${AUTHZ_POLICY} \
    --source=${AUTHZ_POLICY}.yaml \
    --location=${REGION}

Codelab ini memastikan bahwa Anda tidak akan mengalami penolakan akses IAP secara default. Namun, untuk membantu pengujian Anda, Agent Gateway memberikan kemampuan observasi mendetail untuk penolakan akses.

Memecahkan masalah dan memantau penolakan otorisasi IAP

Aktifkan Log Analytics di bucket logging _Default:

gcloud logging buckets update _Default --location=global --enable-analytics --async

Buka dasbor Observabilitas Agent Gateway:
Di Konsol Google Cloud, buka halaman Agent Gateway.
Klik nama gateway Anda (misalnya, gateway-xyz).
Klik tab Observability.
Tinjau dasbor Kegagalan Pemberian Otorisasi dan Penolakan 403.

10. Membuat Agen Agent Engine

Membuat Bucket Penyiapan

Buat bucket Cloud Storage di region target untuk menyimpan artefak penyiapan sementara, dependensi, dan konfigurasi deployment selama inisialisasi runtime.

#Staging bucket name needs to be globally unique
export STAGING_BUCKET="agent-temp-bucket-${PROJ_NO}-${USER_IDENTITY}"
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

Aktifkan lingkungan virtual Python

python3 -m venv .venv
source .venv/bin/activate

Mendownload kode agen

git clone https://github.com/gpratikab/gcp-vpcsc-agent.git
cd gcp-vpcsc-agent

Menginstal dependensi

python3 -m pip install --upgrade -r requirements.txt

Memberikan peran IAM ke agen layanan Agent Platform

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/agentgateway.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/ml.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/networkservices.viewer"

Men-deploy agen

python3 deploy_gcp_agent.py create

Ekspor identitas agen yang dicetak dalam output perintah sebelumnya sebagai variabel lingkungan:

#Paste identity of your Agent, it will be printed as the output of the previous command
export AGENT_IDENTITY="principal://PRINCIPAL_ID"
echo $AGENT_IDENTITY

11. Mengizinkan Egress Agen melalui Gateway

Izinkan agen yang baru dibuat untuk mengirim traffic keluar ke googleapis.com.

Catatan: Anda dapat secara selektif memasukkan endpoint ke daftar yang diizinkan menggunakan kemampuan pengamatan Agent Gateway. Agar lebih sederhana, codelab ini mengizinkan akses ke semua API.

Mengonfigurasi aturan kebijakan egress IAM eksplisit memberikan izin agen untuk merutekan panggilan API melalui proxy IAP dan Agent Gateway untuk menjangkau layanan Google Cloud eksternal.

Membuat kebijakan IAM

cat > agent-access-rules.json << EOF
{
  "conditions": {
    "iap.googleapis.com": {
      "description": "Allow access to agent",
      "expression": "(destination.agent_registry.location == 'global') || (destination.unregistered.host.endsWith('googleapis.com'))",
      "title": "agenttogapis"
    }
  },
  "description": "agenttogapis",
  "effect": "ALLOW",
  "excludedPrincipals": [],
  "operation": {
    "excludedPermissions": [],
    "permissions": [
      "iap.googleapis.com/resources.egressViaIAP"
    ]
  },
  "principals": [
    "${AGENT_IDENTITY}"
  ]
}
EOF

Perbarui kebijakan akses

Periksa apakah Anda memiliki kebijakan akses yang sudah ada:

gcloud iam access-policies list --project=${PROJ_ID} --location=global

Tetapkan nama kebijakan akses:

export IAM_ACCESS_POLICY="agent-access-policy"

Untuk membuat kebijakan baru:

gcloud iam access-policies create ${IAM_ACCESS_POLICY} \
  --details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

Atau, perbarui kebijakan yang ada:

gcloud iam access-policies update ${IAM_ACCESS_POLICY} \
  --add-details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

12. Menguji agen

Memvalidasi operasi agen di konsol Google Cloud memverifikasi bahwa komunikasi end-to-end, kebijakan IAM, dan batas Kontrol Layanan VPC berfungsi dengan baik. Sekarang Anda siap menguji agen:

Di Konsol Google Cloud, buka halaman Agent Deployments.
Pilih agen yang di-deploy (gcp_agent_...).
Buka tab Playground.
Di kolom perintah, masukkan: List storage buckets in the current project.
Pastikan agen berhasil menampilkan daftar bucket melalui Agent Gateway pribadi.
Verifikasi bahwa agen tidak dapat mengambil bucket dari project lain karena penolakan akses. Anda dapat memeriksa penolakan di Cloud Audit Logs atau dasbor pelanggaran Kontrol Layanan VPC.

13. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, hapus project yang Anda buat:

gcloud projects delete ${PROJ_ID}

14. Selamat

Selamat! Anda telah berhasil mengonfigurasi Agen dan Agent Gateway dalam perimeter Kontrol Layanan VPC yang aman di Google Cloud.

Apa selanjutnya?

Pelajari aturan ingress dan egress terperinci di Kontrol Layanan VPC.
Konfigurasi akses dan kebijakan semantik menggunakan Agent Gateway.
Mengintegrasikan Model Armor untuk pemfilteran keamanan dan keselamatan tingkat lanjut.