本頁面的部分或所有資訊可能不適用於 S3NS 的 Cloud de Confiance。詳情請參閱「與 Google Cloud 的差異」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用沙箱設定 VPC Service Controls 和 Private Service Connect

使用 Private Service Connect (PSC-E / PSC-I)，控管 Agent Platform 沙箱的私人連入和網際網路輸出。這些控制項可讓沙箱符合 perimeter 內或沒有 perimeter 的 VPC Service Controls。

總覽

VPC Service Controls 可讓您定義 service perimeter，隔離 Cloud de Confiance by S3NS 資源，降低資料竊取的風險。Gemini Enterprise Agent Platform 沙箱提供安全、隔離的運算環境，可讓代理執行不受信任的程式碼、操作網路瀏覽器 (電腦使用)，或執行自訂容器映像檔。沙箱會公開互動式資料層並發出外撥通話，因此由兩項 Private Service Connect 控制項控管：私人輸入 (PSC-E) 和輸出控制項 (PSC-I)。

在 perimeter 內執行沙箱時，下列項目會在邊界內受到保護：

代理在沙箱工作階段期間讀取或寫入的資料 (沙箱磁碟上的檔案、記憶體內狀態)。
沙箱快照會擷取磁碟和記憶體內狀態，並自動儲存在 Cloud Storage bucket。
與沙箱資料層交換的要求和回覆 (例如電腦使用指令和螢幕截圖)。
從 Artifact Registry 提取的自訂容器映像檔。
沙箱對 Google API (例如 Cloud Storage 或 Agent Platform) 發出的呼叫。

您也可以在沒有 VPC Service Controls perimeter 的情況下設定輸入和輸出控制項，因為 PSC-E (私人輸入) 和 PSC-I (輸出) 是讓沙箱符合 VPC Service Controls 規範的要素。如要設定輸入和輸出，但不使用 VPC Service Controls perimeter，請跳至「使用 Private Service Connect 介面 (PSC-I) 控制沙箱輸出」。

限制和注意事項

私有 Ingress 只能為一個消費者專案啟用，且必須與 Sandbox 執行的使用者專案相同。
僅支援透過 DNS 對接進行私人解析，公開 DNS 轉送功能已停用，以防通道。
受 VPC Service Controls 保護的資源無法使用要求和回應記錄功能。
除非呼叫端位於存取層級，否則無法從 perimeter 外部透過程式和控制台存取。

事前準備

建立或找出包含專案的 VPC Service Controls service perimeter。如要透過 VPC Service Controls 範圍保護沙箱，您必須先將 Cloud de Confiance by S3NS 專案納入範圍，才能建立沙箱。
在專案中啟用 Agent Platform API (aiplatform.googleapis.com)。
在執行沙箱的區域中，具備虛擬私有雲網路。
確認您具備必要角色：
- 周邊的 Access Context Manager 管理員角色
- 在擁有網路連結的專案中，具備 Compute 網路管理員 (roles/compute.networkAdmin) 角色。

將 Agent Platform 新增至服務範圍

將 Agent Platform API 新增至 VPC Service Controls perimeter 的受限服務清單。這項設定可保護 Agent Platform (包括沙箱控制層)，並禁止透過公開網路連線能力存取 API，除非呼叫端位於存取層級。

在 Cloud de Confiance 控制台中開啟「VPC Service Controls」，然後編輯 perimeter。
在「受限制的服務」下方，新增「Vertex AI API」 (aiplatform.googleapis.com)。
確保沙箱使用的依附元件位於相同 perimeter，通常是 Cloud Storage (storage.googleapis.com) 和 Artifact Registry (artifactregistry.googleapis.com，用於自訂容器映像檔)。系統會自動處理快照儲存作業。
如要還原 perimeter 外部信任使用者 (例如公司網路) 的存取權，請將存取層級附加至 perimeter。

選用：設定 Google API 的私人存取權

在 VPC Service Controls 範圍內，沙箱會透過受限制的虛擬 IP 位址 (VIP) 私下連線至 Google API。從您自己的虛擬私有雲和地端部署網路，也請使用受限制的 VIP，確保要求絕不會通過公用網際網路。

將 *.googleapis.com 轉送至受限 VIP 199.36.153.4/30，並在呼叫 Google API 的子網路上啟用私人 Google 存取權。
為 googleapis.com (以及 pkg.dev / gcr.io，如果提取映像檔) 建立 Cloud DNS 私人區域，解析為受限 VIP。

使用 Private Service Connect 介面 (PSC-I) 控制沙箱輸出

如要讓沙箱連上網際網路或私人服務，請使用 Private Service Connect 介面，將沙箱的輸出流量橋接至 VPC，然後使用自己的輸出控制項管理該流量。

這個步驟中的每項資源，都是在擁有沙箱的使用者專案或其 Shared VPC 主專案中建立。輸出流量會導向您在範本中設定的單一虛擬私有雲網路和網路連結。

建立網路連結

為沙箱建立網路連結：

# A dedicated subnet for the PSC interface (minimum /28)
gcloud compute networks subnets create sandbox-psc-subnet \
    --network=YOUR_VPC \
    --range=10.0.0.0/28 \
    --region=REGION

# The network attachment the sandbox connects into
gcloud compute networks network-attachments create sandbox-egress-na \
    --region=REGION \
    --connection-preference=ACCEPT_AUTOMATIC \
    --subnets=sandbox-psc-subnet

從沙箱範本參照附件

設定 SandboxEnvironmentTemplate 的輸出欄位，讓沙箱透過虛擬私有雲轉送輸出流量：

from vertexai import Client

client = Client(project="PROJECT_ID", location="REGION",
                http_options={"api_version": "v1beta1"})

templates = client.agent_engines.sandboxes.templates
op = templates.create(
    name=agent_instance_name,
    display_name="cu-vpcsc-template",
    config={
        "custom_container_environment": {
            "custom_container_spec": {"image_uri": "IMAGE_URI"},
            "ports": [{"port": 8080, "protocol": "TCP"}],
        },
        "egress_control_config": {
            "internet_access": True, # Enables outbound access from the sandbox. With VPC-SC, that traffic is bridged into your VPC.
            "customer_vpc_network":
                "projects/PROJECT_ID/global/networks/YOUR_VPC", # The VPC network in your project that egress is bridged into. Checked by VPC-SC at creation time.
            "network_attachment":
                "projects/PROJECT_ID/regions/REGION/networkAttachments/sandbox-egress-na", # The network attachment that accepts the sandbox's PSC interface.
        },
    },
)

PSC 介面會建立通往虛擬私有雲的私人路徑，啟用 internet_access 後，平台會自動將沙箱的輸出流量導向該路徑。

如要設定及控管虛擬私有雲的輸出路徑，請決定是否需要網際網路或僅限私有輸出：

網際網路輸出：如要輸出至網際網路，必須使用 Cloud NAT，並透過 Cloud Next Generation Firewall (Cloud NGFW) 規則或 Secure Web Proxy 控管目的地。
僅限私人網路的輸出流量 (存取虛擬私有雲或地端部署中的服務，不連上網際網路)：不需要 Cloud NAT。您只需要路由、防火牆規則和 DNS 對接。

設定網際網路輸出及控管目的地

沙箱會透過內部 (RFC 1918) 位址進入 VPC，因此需要 Cloud NAT 才能連上網際網路。如果目的地是依來源 IP 位址加入許可清單，請保留靜態輸出 IP。

# Reserve a static egress IP (optional, for destination-side allow-listing)
gcloud compute addresses create sandbox-egress-ip --region=REGION

# Cloud Router + NAT for the region, scoped to the PSC subnet
gcloud compute routers create sandbox-egress-router \
    --network=YOUR_VPC --region=REGION

gcloud compute routers nats create sandbox-egress-nat \
    --router=sandbox-egress-router --region=REGION \
    --nat-external-ip-pool=sandbox-egress-ip \
    --nat-custom-subnet-ip-ranges=sandbox-psc-subnet

如要限制沙箱在流量通過虛擬私有雲時可觸及的目的地，請選擇所需的控管層級：

Cloud NGFW (網路層級)：全域網路防火牆政策，包含允許規則 (支援 FQDN 物件)，以及預設拒絕其他所有項目：

gcloud compute network-firewall-policies create sandbox-egress-policy --global

# Allow only the destinations your agent needs (by FQDN)
gcloud compute network-firewall-policies rules create 1000 \
    --firewall-policy=sandbox-egress-policy --global-firewall-policy \
    --direction=EGRESS --action=allow --layer4-configs=tcp:443 \
    --dest-fqdns=api.partner.example.com

# Default-deny the rest of egress
gcloud compute network-firewall-policies rules create 65000 \
    --firewall-policy=sandbox-egress-policy --global-firewall-policy \
    --direction=EGRESS --action=deny --layer4-configs=all \
    --dest-ip-ranges=0.0.0.0/0

gcloud compute network-firewall-policies associations create \
    --firewall-policy=sandbox-egress-policy --global-firewall-policy \
    --network=YOUR_VPC

Secure Web Proxy (應用程式/L7)：在虛擬私有雲中部署 Secure Web Proxy 做為輸出檢查點，以啟用 TLS 感知、網址層級政策，並透過該 Proxy 轉送 PSC 子網路的輸出流量。

設定僅限私人的輸出

如果沙箱只需要虛擬私有雲或地端部署中的私人服務，請確保虛擬私有雲有前往目的地的路徑，並透過 PSC 子網路 (10.0.0.0/28) 的輸出防火牆規則允許該路徑，然後透過 DNS 對接解析服務名稱。

設定 DNS 對接

透過 VPC 提供沙箱名稱解析，而非公用解析器 (這也會封鎖 DNS 通道外洩)。在虛擬私有雲中建立 Cloud DNS 私人區域，並加入沙箱所需的記錄，然後設定 DNS 對接，讓沙箱解析該區域的名稱。

授予服務代理存取權 (Shared VPC)

如果網路連結所在的專案 (專案 A) 與執行沙箱的專案 (專案 B) 不同，請在專案 A 中，將 Compute 網路使用者角色授予專案 B 的 Agent Platform 服務代理程式。

# Agent Platform service agent of the project that runs the sandbox
service-PROJECT_NUMBER@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com

# On the project that owns the network attachment
gcloud projects add-iam-policy-binding NETWORK_PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/compute.networkUser"

更改下列內容：

PROJECT_NUMBER：執行沙箱的專案編號。
NETWORK_PROJECT_ID：網路連結所屬專案的 ID。

使用 Private Service Connect (PSC-E) 啟用私人輸入

互動式工作負載會公開用戶端必須連線的資料層。透過虛擬私有雲中的私人 Private Service Connect 端點 (PSC-E) 存取該資料層，而非透過公開網際網路。

宣告允許的消費者專案

在範本上設定輸入設定，並允許消費端專案連線。只有執行沙箱的相同使用者專案，才能透過私人輸入連至沙箱虛擬私有雲。

從同一專案的虛擬私有雲連線至沙箱：

config = {
    # ...custom_container_environment, egress_control_config...
    "ingress_control_config": {
        "private_service_connect_config": {
            # Must be the same project the sandbox runs in.
            "enable_private_service_connect": True,
        }
    },
}

在虛擬私有雲建立 PSC 端點

建立沙箱後，請從連線資訊讀取服務連結，並在虛擬私有雲中使用轉送規則 (PSC 端點) 指定該連結：

# The sandbox returns a service attachment to connect to
service_attachment = sandbox.connection_info.service_attachment

# Reserve an internal IP and create the PSC endpoint
gcloud compute addresses create sandbox-ingress-ip \
    --region=REGION --subnet=YOUR_SUBNET

gcloud compute forwarding-rules create sandbox-ingress-ep \
    --region=REGION \
    --network=YOUR_VPC \
    --address=sandbox-ingress-ip \
    --target-service-attachment=SERVICE_ATTACHMENT_URI

該專案虛擬私有雲中的用戶端 (或可透過該虛擬私有雲連線的用戶端)，現在會透過端點的私人 IP 連線至沙箱 (例如透過沙箱 WebSocket 或 CDP 通訊埠連線的用戶端)。

後續步驟

請參閱「沙箱總覽」和「自備容器 (BYOC)」。
瞭解 Private Service Connect 介面如何與 Agent Runtime 搭配運作。
請參閱 VPC Service Controls 疑難排解。
如需完整的輸出逐步操作說明，請參閱 Agent Engine PSC 介面程式碼實驗室。