1. 簡介
本程式碼實驗室會引導您設定 Google Cloud 環境，透過 VPC Service Controls 範圍設定代理程式和 Agent Gateway。建立 VPC Service Controls 防護邊界、設定網路和 DNS、部署 Agent Gateway 並啟用 Identity-Aware Proxy (IAP) 要求授權，然後安全地測試代理程式。
建構項目
在本程式碼研究室中，您將為 Gemini Enterprise Agent Platform 和 Agent Gateway 建構安全的 Google Cloud 架構，以執行下列操作：
- 使用 VPC Service Controls 保護專案資源，防範未經授權的資料竊取行為。
- 設定 Private Google Access、Private Service Connect (PSC) 和 Cloud DNS 私人區域，以進行非公開 API 路由。
- 佈建 Agent Gateway，集中式流量 Proxy、輸出規則和通訊協定設定。
- 強制執行 Identity-Aware Proxy (IAP) 要求授權政策。
- 透過私密連線部署及安全測試 Agent Engine 代理程式。
課程內容
- 如何啟用 Agent Platform 和安全防護所需的 Google Cloud API。
- 如何設定 VPC Service Controls 範圍和輸入存取規則。
- 如何設定私人網路連線和私人 DNS 記錄。
- 如何建立 Agent Gateway 和代理程式連線能力範本。
- 如何設定 IAP 要求授權擴充功能和政策。
- 如何安全地部署及測試 Agent Engine 代理程式。
軟硬體需求
- 已安裝 Google Cloud CLI，並更新至最新版本。
- 工作站上已安裝 Python 3。
- 工作站上已安裝 Git。
- 有效的 Google Cloud 機構和帳單帳戶權限。
2. 先決條件
本節將概述基本指令列工具需求，以及執行設定指令碼前所需的環境設定。
- 確認已安裝 Google Cloud CLI 並更新至最新版本，然後使用 Google 帳戶進行驗證。更新 Google Cloud CLI 元件，確保您擁有網路服務和 VPC Service Controls 的最新功能支援。
gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL
- 確認已安裝 Python 3，以便設定及部署自訂代理程式架構。如需操作說明，請參閱「安裝 Python 模組」：
python3 --version
- 請務必安裝 Git，以便複製包含設定碼和設定範本的範例存放區。如需操作說明，請參閱「Git 安裝」一文。
3. 設定 Google Cloud 專案
在機構內建立獨立專案，可確保本程式碼研究室使用的所有資源、網路和權限都受到封裝，且易於管理。進一步瞭解如何建立及管理專案。
在機構底下初始化新的 Google Cloud 雲端專案，以代管這項設定的資源。您也可以使用自己的專案：
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
登入以取得應用程式預設憑證：
gcloud auth application-default login
驗證設定：
gcloud config list
啟用計費功能
將有效的帳單帳戶連結至新建立的專案，啟用服務使用權。
您必須先啟用帳單功能，才能使用 API 配額，以及佈建 Google Cloud 雲端基礎架構，例如 Agent Gateway、虛擬私有雲和運算節點。如要瞭解帳單設定詳情，請參閱 Google Cloud Billing 說明文件。
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. 啟用服務
啟用 Agent、Agent Gateway、網路、安全性及可觀測性功能的所有必要 Google Cloud API。
啟用 API 後，即可使用後端雲端服務，進行 Resource Manager、觀測能力及網路功能，確保代理程式連線能力安全。詳情請參閱「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. 匯出環境變數
為區域、專案 ID、專案編號、組織 ID 和使用者身分定義可重複使用的環境變數。設定殼層變數可讓各步驟的資源設定指令標準化，減少指令碼執行期間的手動替換錯誤。
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. 建立 VPC Service Controls 服務範圍
建立 VPC Service Controls perimeter，隔離專案資源並防範資料竊取。詳情請參閱「VPC Service Controls 總覽」。
擷取存取權政策
擷取與貴機構相關聯的 Access Context Manager 政策 ID。Access Context Manager 政策會定義組織界線，VPC Service Controls perimeter 會附加至該界線並強制執行。
gcloud access-context-manager policies list --organization=$ORG_ID
匯出存取權政策
在 gcloud CLI 設定中設定存取權政策，並收集支援的受限服務清單。收集所有支援的服務，即可建構受限制的 perimeter 規則集，防止未經授權存取 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, -)
建立 perimeter
定義服務安全防護範圍名稱，並在專案中對支援的 Google Cloud 服務強制執行限制。perimeter 會做為專案資源周圍的邊界，限制直接傳入和傳出流量，除非傳入/傳出規則明確允許。
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}
建立輸入政策
Ingress 政策會定義明確條件 (例如特定使用者身分或存取層級)，規定從 perimeter 外部發起的流量，在符合條件時可存取內部的受限資源。
建立 YAML 檔案，允許使用者身分跨所有服務的明確存取權：
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"
本程式碼實驗室會設定環境，預設避免 VPC Service Controls 拒絕存取。不過，為了協助您在測試期間排解問題，VPC Service Controls 提供詳細的拒絕記錄和政策智慧工具。
排解 VPC Service Controls 拒絕存取的問題
測試期間，請參考下列疑難排解提示：
- 啟用違規資訊主頁，追蹤環境中的最新違規事項。
- 監控 Cloud 稽核記錄，找出 VPC Service Controls 存取遭拒 (403) 記錄。
- 使用違規分析工具中的違規專屬 ID 或權杖診斷違規問題。
- 如需詳細逐步說明，請觀看「Troubleshooting VPC Service Controls」影片。
7. 設定網路
設定虛擬私有雲網路，支援與 Google API 和服務的私人通訊。適當的網路設定可確保代理程式、閘道和 Google Cloud API 之間的網路流量，會保留在私人內部網路上。如需詳細的網路模式，請參閱 Google Cloud 虛擬私有雲說明文件。
啟用 Private Google Access
在預設子網路上啟用 Private Google Access，讓 VM 執行個體和內部工作負載可以使用內部 IP 位址 (而非公開 IP 位址) 存取 Google API。
export NETWORK_NAME="default"
export SUBNET_NAME="default"
gcloud compute networks subnets update $SUBNET_NAME --region=$REGION --enable-private-ip-google-access
建立 PSC 網路連結
為 Agent Gateway 連線建立 Private Service Connect (PSC) 網路連結。網路附件提供 Private Service Connect (PSC) 介面，方便 Agent Gateway 服務與內部子網路之間進行安全的跨 VPC 通訊。
gcloud compute network-attachments create psc-agw-${REGION} \
--region=${REGION} \
--subnets=${SUBNET_NAME} \
--connection-preference=ACCEPT_AUTOMATIC
驗證
擷取並檢查新建立的網路連結的自我連結資源 URI。驗證資源 URI 可確保網路連結已成功例項化，並可在連線範本中參照。
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-agw-${REGION} \
--region=${REGION} \
--format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}
建立 Cloud DNS 私人區域
設定 Cloud DNS 私人區域，透過私人 IP 範圍轉送 googleapis.com 流量。私人 DNS 區域會覆寫 googleapis.com 的公用網域查詢，將所有輸出流量導向虛擬私有雲網路中的私人內部虛擬 IP (VIP)。詳情請參閱「Cloud DNS 私人區域」。
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}
選擇下列其中一個私人路由網域選項 (執行交易前，請只執行選項 1 或選項 2 下方的指令) - 詳情請參閱「私人 Google 存取權設定選項」：
選項 1：私人 VIP [建議]
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
選項 2：受限制 VIP
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
提交 DNS 交易：
gcloud dns record-sets transaction execute --zone=${ZONE_NAME}
8. 建立代理程式閘道
佈建 Agent Gateway，並定義其連線範本和轉送規則。Agent Gateway 可做為集中式 Proxy，用於管理代理流量、輸出政策、通訊協定處理和安全服務探索。如需架構參考資料，請參閱「Agent Gateway 總覽」。
export AGW_NAME="gateway-${USER_IDENTITY}"
export AGW_CONNECTIVITY_TEMPLATE="agw-connectivity-template-${USER_IDENTITY}"
建立代理程式連線範本
連線範本會指定閘道處理輸出要求時所需的網路設定、輸出轉送政策、DNS 對接設定和網路連結 URI。
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}
建立 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}
確認建立作業
確認 Agent Gateway 資源已成功部署及設定。描述已部署的代理程式閘道，確認其運作狀態為有效，並驗證相關聯的連線範本和登錄檔是否已正確附加。
gcloud network-services agent-gateways describe ${AGW_NAME} \
--location=${REGION}
9. 透過 IAP 建立授權
設定 Identity-Aware Proxy (IAP) 要求授權政策和服務擴充功能，先驗證要求憑證，再授予 Agent Gateway 存取權。詳情請參閱 IAP 說明文件。
export AUTHZ_EXT="iap-authz-extension-${USER_IDENTITY}"
export AUTHZ_POLICY="iap-authz-policy-${USER_IDENTITY}"
建立 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}
建立授權政策並繫結至 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}
本程式碼實驗室可確保您預設不會遭到 IAP 拒絕存取。不過，為了協助您進行測試，代理閘道會提供詳細的存取遭拒可觀測性。
排解及監控 IAP 授權遭拒問題
- 在「_Default」記錄 bucket 中啟用記錄檔分析：
gcloud logging buckets update _Default --location=global --enable-analytics --async
- 開啟 Agent Gateway Observability 資訊主頁：
- 前往 Google Cloud 控制台的「Agent Gateway」頁面。
- 按一下閘道名稱 (例如 gateway-xyz)。
- 按一下「可觀測性」分頁標籤。
- 查看「授權失敗」和「403 拒絕」資訊主頁。
10. 建立 Agent Engine 代理程式
建立暫存 bucket
在目標區域中建立 Cloud Storage bucket，在執行階段初始化期間儲存臨時暫存構件、依附元件和部署設定。
#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}
啟動 Python 虛擬環境
python3 -m venv .venv
source .venv/bin/activate
下載代理程式碼
git clone https://github.com/gpratikab/gcp-vpcsc-agent.git
cd gcp-vpcsc-agent
安裝依附元件
python3 -m pip install --upgrade -r requirements.txt
將 IAM 角色授予 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"
部署代理
python3 deploy_gcp_agent.py create
將上一個指令輸出內容中列印的代理程式身分匯出為環境變數：
#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. 允許透過閘道輸出代理程式
允許新建立的代理程式將輸出流量傳送至 googleapis.com。
注意：您可以使用 Agent Gateway 可觀測性，選擇性地將端點加入允許清單。為求簡化，本程式碼研究室允許存取所有 API。
設定明確的 IAM 輸出政策規則，可授予代理權限，透過 Agent Gateway 和 IAP Proxy 傳送 API 呼叫，連線至外部 Google Cloud 服務。
建立身分與存取權管理政策
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
更新存取權政策
檢查是否已有存取權政策：
gcloud iam access-policies list --project=${PROJ_ID} --location=global
設定存取權政策名稱：
export IAM_ACCESS_POLICY="agent-access-policy"
建立新政策的方法：
gcloud iam access-policies create ${IAM_ACCESS_POLICY} \
--details-rules=agent-access-rules.json \
--project=${PROJ_ID} \
--location=global
或者，您也可以更新現有政策：
gcloud iam access-policies update ${IAM_ACCESS_POLICY} \
--add-details-rules=agent-access-rules.json \
--project=${PROJ_ID} \
--location=global
12. 測試代理
在 Google Cloud 控制台中驗證代理程式作業，可確認端對端通訊、IAM 政策和 VPC Service Controls 邊界是否正常運作。現在可以測試代理程式了：
- 前往 Google Cloud 控制台的「代理程式部署」頁面。
- 選取已部署的代理 (
gcp_agent_...)。 - 開啟「Playground」分頁。
- 在提示欄位中輸入：
List storage buckets in the current project. - 確認代理程式是否透過私有 Agent Gateway 成功傳回 bucket 清單。
- 確認由於存取遭拒，代理程式無法從其他專案擷取 bucket。您可以在 Cloud 稽核記錄或 VPC Service Controls 違規資訊主頁中檢查拒絕存取記錄。
13. 清理
如要避免系統向您的 Google Cloud 帳戶收取本程式碼研究室所用資源的費用，請刪除您建立的專案：
gcloud projects delete ${PROJ_ID}
14. 恭喜
恭喜！您已在 Google Cloud 的安全 VPC Service Controls 範圍內，成功設定 Agent 和 Agent Gateway。
後續步驟
- 瞭解 VPC Service Controls 中的精細輸入和輸出規則。
- 使用 Agent Gateway 設定存取權和語意政策。
- 整合 Model Armor，進行進階安全和安全篩選。