配置具有沙盒的 VPC Service Controls 和 Private Service Connect

使用 Private Service Connect (PSC-E / PSC-I) 控制 Agent Platform 沙盒的专用入站流量和互联网出站流量。借助这些控制措施，沙盒可以在边界内或没有边界的情况下符合 VPC Service Controls 的要求。

概览

借助 VPC Service Controls，您可以定义服务边界来隔离 Cloud de Confiance by S3NS 资源，从而降低数据渗漏的风险。Gemini Enterprise Agent Platform 沙盒为您的智能体提供了一个安全、隔离的算力环境，以便运行不受信任的代码、驱动网络浏览器（计算机使用）或执行自定义容器映像。沙盒会公开交互式数据平面并进行出站调用，因此它受两个 Private Service Connect 控制措施的约束：专用入站流量 (PSC-E) 和出站流量控制 (PSC-I)。

在边界内运行沙盒时，以下内容会在您的边界内受到保护：

  • 代理在沙盒会话期间读取或写入的数据（沙盒磁盘上的文件、内存中的状态）。
  • 沙盒 快照，用于捕获磁盘和内存中的状态，并自动存储在 Cloud Storage 存储桶中。
  • 与沙盒数据平面交换的请求和响应（例如，计算机使用命令和屏幕截图）。
  • 从 Artifact Registry 中拉取的自定义容器映像。
  • 沙盒对 Google API（例如 Cloud Storage 或 Agent Platform）的调用。

您还可以在没有 VPC Service Controls 边界的情况下设置入站流量和出站流量控制，因为 PSC-E（专用入站流量）和 PSC-I（出站流量）是使沙盒符合 VPC Service Controls 要求的因素。如需在没有 VPC Service Controls 边界的情况下设置入站流量和出站流量，请跳至使用 Private Service Connect 接口 (PSC-I) 控制沙盒出站流量。

限制和注意事项

  • 专用入站流量只能为一个使用方项目启用，并且该项目必须与沙盒运行的用户项目相同。
  • 仅支持通过 DNS 对等互连进行专用解析；公共 DNS 转发功能已停用，以防止隧道传输。
  • VPC Service Controls 保护的资源无法使用请求和响应日志记录。
  • 除非调用方具有访问权限级别，否则系统会拒绝从边界外进行程序化访问和控制台访问。

准备工作

  • 创建或确定包含您的项目的 VPC Service Controls 服务边界。为了让沙盒受到 VPC Service Controls 边界的保护，您必须先将 Cloud de Confiance by S3NS 项目添加到边界内，然后才能创建沙盒。
  • 在您的项目中启用 Agent Platform API (aiplatform.googleapis.com)。
  • 在运行沙盒的区域中拥有 VPC 网络。
  • 确认您拥有所需的角色：

将 Agent Platform 添加到服务边界

将 Agent Platform API 添加到 VPC Service Controls 边界的受限服务列表中。这样可以保护 Agent Platform（包括沙盒控制平面），并阻止对 API 的公共互联网访问，除非调用方具有 访问权限级别。

  1. 在 Cloud de Confiance 控制台中打开 VPC Service Controls 并修改边界。
  2. 在受限服务 下，添加 Vertex AI API (aiplatform.googleapis.com)。
  3. 确保沙盒使用的依赖项位于同一边界内，通常是 Cloud Storage (storage.googleapis.com) 和 Artifact Registry (artifactregistry.googleapis.com，用于自定义容器映像)。系统会自动为您处理快照存储。
  4. 如需恢复边界外受信任用户（例如您的公司网络）的访问权限，请将访问权限级别附加到边界。

可选：配置对 Google API 的专用访问通道

在 VPC Service Controls 边界内，沙盒通过受限虚拟 IP 地址 (VIP) 以私密方式访问 Google API。从您自己的 VPC 和本地网络中，也使用受限 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，然后使用您自己的出站流量控制措施来管理该流量。

此步骤中的每个资源都是在拥有沙盒的用户项目或其共享 VPC 宿主项目中创建的。出站流量会定向到您在模板上设置的单个 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 上设置出站流量字段，以便沙盒通过您的 VPC 路由出站流量：

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 接口会在您的 VPC 中构建专用路径，并且在启用 internet_access 后，平台会自动将沙盒的出站流量引导到该路径。

如需设置和管理 VPC 的出站路径，请确定您需要互联网出站流量还是仅需要专用出站流量：

  • **互联网出站流量**：对于互联网出站流量，需要 Cloud NAT，以及使用 Cloud Next Generation Firewall (Cloud NGFW) 规则或 Secure Web Proxy 进行目标控制。
  • **仅专用出站流量** （访问 VPC 或本地服务，无需互联网）：不需要 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

如需限制沙盒在流量通过您的 VPC 时可以访问的目标，请选择您需要的控制级别：

  • 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 部署为 VPC 中的出站流量检查点，以实现 TLS 感知、按网址政策，并通过该代理路由 PSC 子网的出站流量。

设置仅专用出站流量

如果沙盒只需要 VPC 或本地专用服务，请确保您的 VPC 具有到达目标的路由，使用 PSC 子网 (10.0.0.0/28) 的出站流量防火墙规则允许该路由，并通过 DNS 对等互连解析服务名称。

设置 DNS 对等互连

通过您的 VPC 而不是公共解析器为沙盒提供域名解析（这也会阻止 DNS 隧道渗漏）。在您的 VPC 中创建一个 Cloud DNS 专用区域，其中包含沙盒所需的记录，然后配置 DNS 对等互连，以便沙盒从该区域解析名称。

授予服务代理访问权限（共享 VPC）

如果网络连接位于与运行沙盒的项目（项目 B）不同的项目（项目 A）中，请向项目 B 的 Agent Platform 服务代理授予项目 A 的 Compute Network User 角色。

# 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) 启用专用入站流量

交互式工作负载会公开客户端必须连接的数据平面。通过 VPC 中的专用 Private Service Connect 端点 (PSC-E) 而不是通过公共互联网访问该数据平面。

声明允许的使用方项目

在模板上设置入站流量配置，并允许使用方项目进行连接。只有沙盒运行的同一用户项目才能具有对沙盒 VPC 的专用入站流量。

从同一项目中的 VPC 连接到沙盒：

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,
        }
    },
}

在 VPC 中创建 PSC 端点

创建沙盒后，从其连接信息中读取服务连接，并使用 VPC 中的转发规则（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

该项目的 VPC 中的客户端（或可通过该 VPC 访问的客户端）现在通过端点的专用 IP 连接到沙盒（例如，通过沙盒 WebSocket 或 CDP 端口连接的客户端）。

后续步骤