Cloud Run 沙盒提供了一个快速、安全且隔离的环境,用于为现有实例上托管的智能体运行不受信任的代码执行工具或浏览器自动化软件。沙盒针对延迟时间进行了高度优化,并在与容器相同的实例中运行,共享其分配的 CPU 和内存。
本页面介绍了如何在容器上配置沙盒。如需详细了解如何编写代码以使用 CLI 与沙盒交互,请参阅 Cloud Run 中的代码执行。
准备工作
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- 安装并初始化 gcloud CLI。
- 部署 Cloud Run 实例。
所需的角色
如需获得配置和部署 Cloud Run 实例所需的权限,请让您的管理员为您授予以下 IAM 角色:
- Cloud Run 实例的 Cloud Run Developer (
roles/run.developer) 角色 - 服务身份的 Service Account User (
roles/iam.serviceAccountUser) 角色
如需查看与 Cloud Run 关联的 IAM 角色和权限的列表,请参阅 Cloud Run IAM 角色和 Cloud Run IAM 权限。如果您的 Cloud Run 实例与Google Cloud API(例如 Cloud 客户端库)进行交互,请参阅服务身份配置指南。如需详细了解如何授予角色,请参阅部署权限和管理访问权限。
启用沙盒
如需在 Cloud Run 实例中启用沙盒,请使用 Google Cloud CLI 或 YAML 配置:
gcloud
如需创建或更新实例,请指定 --sandbox-launcher 标志:
如需创建新实例,请运行以下命令:
gcloud beta run instances create INSTANCE --image IMAGE_URL --sandbox-launcher
替换以下内容:
- INSTANCE:Cloud Run 实例的名称。
IMAGE_URL:对容器映像的引用,例如us-docker.pkg.dev/cloudrun/container/hello:latest。
如需更新现有实例,请运行以下命令:
gcloud beta run instances update INSTANCE --sandbox-launcher
YAML
如果您要创建新实例,请跳过此步骤。如果您要更新现有实例,请下载其 YAML 配置:
gcloud beta run instances describe INSTANCE --format export > instance.yaml
更新 YAML 文件,在容器配置中添加设置为
true的sandboxLauncher属性:apiVersion: run.googleapis.com/v1 kind: Instance metadata: name: INSTANCE annotations: run.googleapis.com/launch-stage: BETA spec: containers: - name: CONTAINER image: IMAGE_URL sandboxLauncher: true替换以下内容:
- INSTANCE:Cloud Run 实例的名称。
- CONTAINER:容器的名称。
IMAGE_URL:对容器映像的引用,例如us-docker.pkg.dev/cloudrun/container/hello:latest。
使用以下命令创建或更新实例:
gcloud beta run instances replace instance.yaml
沙盒会共享分配给宿主容器的 CPU 和内存。请确保主容器的 CPU 和内存限制足以同时容纳应用和您同时运行的所有活跃沙盒。
停用沙盒
如需停用在实例中启动沙盒的功能,请使用 Google Cloud CLI 或 YAML 配置:
gcloud
运行以下命令,使用 --no-sandbox-launcher 标志更新实例:
gcloud beta run instances update INSTANCE --no-sandbox-launcher
将 INSTANCE 替换为您的实例名称。
YAML
如果您要创建新实例,请跳过此步骤。如果您要更新现有实例,请下载其 YAML 配置:
gcloud beta run instances describe INSTANCE --format export > instance.yaml
更新 YAML 文件,移除容器配置中的
sandboxLauncher属性:apiVersion: run.googleapis.com/v1 kind: Instance metadata: name: INSTANCE spec: containers: - name: CONTAINER image: IMAGE_URL替换以下内容:
- INSTANCE:Cloud Run 实例的名称。
- CONTAINER:容器的名称。
IMAGE_URL:对容器映像的引用,例如us-docker.pkg.dev/cloudrun/container/hello:latest。
使用以下命令创建或更新实例:
gcloud beta run instances replace instance.yaml
查看沙盒设置
如需查看 Cloud Run 实例的当前沙盒设置,请执行以下操作:
gcloud
使用以下命令:
gcloud beta run instances describe INSTANCE
将 INSTANCE 替换为您的实例名称。
在返回的配置中找到
sandboxLauncher: true属性。
如需在实例的沙盒中运行不受信任的代码,请参阅 Cloud Run 中的代码执行。
配置沙盒模板
借助沙盒模板,您可以为沙盒定义容器映像。sandbox do
--template 和 sandbox run --template 命令不会在主应用容器内运行沙盒会话,而是使用您指定的映像(例如 Python、Node.js 或自定义执行环境)启动新容器。这些沙盒在各自的容器中运行,并共享主容器的 CPU 和内存限制。您无法为模板设置单独的 CPU 和内存限制。Cloud Run 最多支持 10 个沙盒模板。
卷装载必须引用 Cloud Run 资源上的内存中卷。
沙盒模板提供以下功能:
专用容器映像:将不同的容器映像(例如
python:3.12-slim或busybox:latest)声明为沙盒模板。您还可以使用主容器不需要的其他运行时和工具来创建沙盒。通过隔离仅用于沙盒化的工具和运行时,这可以使主容器保持轻量。按需实例化:沙盒 CLI (
/usr/local/gcp/bin/sandbox) 会根据模板生成新的沙盒容器,而无需预配新的虚拟机或为新实例付费。每个沙盒的隔离文件共享:在主容器和多个沙盒之间共享内存中卷,同时将每个沙盒限制在其自己的隔离子目录中,以防止沙盒查看或修改其他文件。
您可以使用 YAML 配置或 Cloud Run Admin API 配置沙盒模板:
YAML
如果您要创建新实例,请跳过此步骤。如果您要更新现有实例,请下载其 YAML 配置:
gcloud beta run instances describe INSTANCE --format export > instance.yaml
更新实例 YAML 文件,以包含
sandboxes模板配置:apiVersion: run.googleapis.com/v1 kind: Instance metadata: name: INSTANCE annotations: run.googleapis.com/launch-stage: BETA spec: containers: - image: IMAGE_URL sandboxLauncher: true volumeMounts: - name: VOLUME_NAME mountPath: CONTAINER_MOUNT_PATH volumes: - name: VOLUME_NAME emptyDir: medium: Memory sandboxes: templates: - name: TEMPLATE_NAME image: TEMPLATE_IMAGE_URL volumeMounts: - name: VOLUME_NAME mountPath: SANDBOX_MOUNT_PATH subPath: SUBPATH替换以下内容:
- INSTANCE:Cloud Run 实例的名称。
- IMAGE_URL:要用于主容器的容器映像网址。
- TEMPLATE_NAME:模板的名称。
- TEMPLATE_IMAGE_URL:要用于沙盒模板的容器映像网址。
- 可选:VOLUME_NAME:要装载的卷的名称。
- 可选:CONTAINER_MOUNT_PATH:主容器内装载卷的路径。
- 可选:SANDBOX_MOUNT_PATH:沙盒容器内装载卷的路径。
- 可选:SUBPATH:要装载到沙盒容器中的卷内的相对子目录路径,例如
my-subdir。如需在运行时为每个沙盒设置不同的子目录,请使用$(VARIABLE_NAME)占位符,例如$(SANDBOX_DIR):- VARIABLE_NAME 只能包含 ASCII 字母和下划线;不支持数字和连字符。
- 如需在运行时解析占位符,请传递
--template-var=VARIABLE_NAME=VALUE标志以及--template。 subPath不会自动创建目录。在运行sandbox do或sandbox run之前,请在主容器的卷中创建解析后的 SUBPATH 目录,例如使用mkdir -p。
使用以下命令创建或更新实例:
gcloud beta run instances replace instance.yaml
REST API
如需配置沙盒模板,请向 Cloud Run Admin API 发送 PATCH 请求:
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -X PATCH \ "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE?updateMask=launchStage,containers,sandboxes,volumes" \ -d '{ "launchStage": "BETA", "containers": [ { "image": "IMAGE_URL", "ports": [ { "containerPort": 8080 } ], "sandboxLauncher": true, "volumeMounts": [ { "name": "VOLUME_NAME", "mountPath": "CONTAINER_MOUNT_PATH" } ] } ], "sandboxes": { "templates": [ { "name": "TEMPLATE_NAME", "image": "TEMPLATE_IMAGE_URL", "volumeMounts": [ { "name": "VOLUME_NAME", "mountPath": "SANDBOX_MOUNT_PATH", "subPath": "SUBPATH" } ] } ] }, "volumes": [ { "name": "VOLUME_NAME", "emptyDir": { "medium": "MEMORY" } } ] }'
替换以下内容:
- INSTANCE:Cloud Run 实例的名称。
- PROJECT_ID:您的 Google Cloud 项目 ID。
- REGION:Cloud Run 资源的部署区域。
- IMAGE_URL:要用于主容器的容器映像网址。
- TEMPLATE_NAME:模板的名称。
- TEMPLATE_IMAGE_URL:要用于沙盒模板的容器映像网址。
- 可选:VOLUME_NAME:要装载的卷的名称。
- 可选:CONTAINER_MOUNT_PATH:主容器内装载卷的路径。
- 可选:SANDBOX_MOUNT_PATH:沙盒容器内装载卷的路径。
- 可选:SUBPATH:要装载到沙盒容器中的卷内的相对子目录路径,例如
my-subdir。如需在运行时为每个沙盒设置不同的子目录,请使用$(VARIABLE_NAME)占位符,例如$(SANDBOX_DIR):- VARIABLE_NAME 只能包含 ASCII 字母和下划线;不支持数字和连字符。
- 如需在运行时解析占位符,请传递
--template-var=VARIABLE_NAME=VALUE标志以及--template。 subPath不会自动创建目录。在运行sandbox do或sandbox run之前,请在主容器的卷中创建解析后的 SUBPATH 目录,例如使用mkdir -p。
如需在实例容器中使用 CLI 运行模板,请参阅使用沙盒模板运行命令。