为服务配置沙盒

Cloud Run 沙盒提供了一个快速、安全且隔离的环境，用于在第二代环境中的现有服务内执行不受信任的代码或运行工具（例如 AI 代理）。沙盒针对延迟进行了高度优化，并且与容器在同一实例中运行，共享其分配的 CPU 和内存。

本页介绍了如何在容器上配置沙盒。 如需详细了解如何使用 CLI 编写与沙盒交互的代码，请参阅 Cloud Run 中的代码执行。

准备工作

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 安装并初始化 gcloud CLI。
  7. 在 第二代 执行环境中部署 Cloud Run 服务。

所需角色

如需获得配置和部署 Cloud Run 服务所需的权限，请让您的管理员为您授予以下 IAM 角色：

如果您要从源代码部署服务 或函数，则 还必须向您授予项目和 Cloud Build 服务帐号的其他角色。

如需查看与 Cloud Run 关联的 IAM 角色和权限的列表，请参阅 Cloud Run IAM 角色和 Cloud Run IAM 权限。如果您的 Cloud Run 服务与Google Cloud API（例如 Cloud 客户端库）进行交互，请参阅服务身份配置指南。如需详细了解如何授予角色，请参阅 部署权限 和管理访问权限。

启用沙盒

任何配置更改都会导致新修订版本的创建。后续修订版本也将自动采用此配置设置，除非您进行了明确更新。

启用沙盒后，Cloud Run 服务会在第二代执行环境中部署。如需在 Cloud Run 服务中启用沙盒，请使用 Google Cloud CLI 或 YAML 配置：

gcloud

如需部署或更新服务，请指定 --sandbox-launcher 标志：

  • 如需部署新服务，请运行以下命令：

    gcloud beta run deploy SERVICE --image IMAGE_URL --sandbox-launcher

    替换以下内容：

    • SERVICE：Cloud Run 服务的名称。
    • IMAGE_URL：对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址采用 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 格式

  • 如需更新现有服务，请运行以下命令：

    gcloud beta run services update SERVICE --sandbox-launcher

YAML

  1. 如果您要创建新的服务，请跳过此步骤。 如果您要更新现有服务，请下载其 YAML 配置：

    gcloud run services describe SERVICE --format export > service.yaml

  2. 更新服务 YAML 文件，以在容器配置中添加设置为 true 的 sandboxLauncher 属性：

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
      - name: CONTAINER
        image: IMAGE_URL
        sandboxLauncher: true
        port: 8080

    替换以下内容：

    • SERVICE：Cloud Run 服务的名称。
    • CONTAINER：容器的名称。
    • IMAGE_URL：对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址采用 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 格式

  3. 使用以下命令创建或更新服务：

    gcloud run services replace service.yaml

    如果存在 service.yaml 文件，gcloud run services replace 命令默认使用该文件。

沙盒共享分配给宿主容器的 CPU 和内存。请确保主容器的 CPU 和内存限制足以容纳您的应用以及您同时运行的任何活跃沙盒。

停用沙盒

如需停用在服务中启动沙盒的功能，请使用 Google Cloud CLI 或 YAML 配置：

gcloud

使用 --no-sandbox-launcher 标志更新服务，方法是运行以下命令：

gcloud beta run services update SERVICE --no-sandbox-launcher

将 SERVICE 替换为服务的名称。

YAML

  1. 如果您要创建新的服务，请跳过此步骤。 如果您要更新现有服务，请下载其 YAML 配置：

    gcloud run services describe SERVICE --format export > service.yaml

  2. 更新服务 YAML 文件，以移除容器配置中的 sandboxLauncher 属性：

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    spec:
      containers:
      - name: CONTAINER
        image: IMAGE_URL
        port: 8080

    替换以下内容：

    • SERVICE：Cloud Run 服务的名称。
    • CONTAINER：容器的名称。
    • IMAGE_URL：对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址采用 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 格式

  3. 使用以下命令创建或更新服务：

    gcloud run services replace service.yaml

    如果存在 service.yaml 文件，gcloud run services replace 命令默认使用该文件。

启动沙盒

启用沙盒后，您可以从容器执行环境内启动沙盒。沙盒二进制文件位于 /usr/local/gcp/bin/sandbox。

您可以通过在源代码中引用二进制文件的绝对路径来执行该二进制文件。例如，如需在隔离的沙盒内输出 Hello，请选择以下选项之一：

Node.js

如需从 Node.js 应用执行沙盒命令，请添加以下代码：

exec(`/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

如需从 Python 应用执行沙盒命令，请添加以下代码：

import subprocess
result = subprocess.run(
    ["/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

如需从 Go 应用执行沙盒命令，请添加以下代码：

cmd := exec.Command("/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

沙盒 CLI

如需直接从命令行执行沙盒命令，请运行以下命令：

/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"

本指南中的示例使用 sandbox 命令，而不是其绝对路径 /usr/local/gcp/bin/sandbox。

如需查看可用命令的完整列表，请运行/usr/local/gcp/bin/sandbox -h命令。

如需在沙盒中运行来自服务的不受信任的代码，请参阅 Cloud Run 中的代码执行。