Cloud Run 沙盒提供了一个快速、安全且隔离的环境,可在第二代环境中的现有服务内执行不可信代码或运行工具(例如 AI 智能体)。沙盒针对延迟时间进行了高度优化,并在与容器相同的实例中运行,共享其分配的 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 Build 服务账号的其他角色。
如需查看与 Cloud Run 关联的 IAM 角色和权限的列表,请参阅 Cloud Run IAM 角色和 Cloud Run IAM 权限。如果您的 Cloud Run 服务与Google Cloud API(例如 Cloud 客户端库)进行交互,请参阅服务身份配置指南。如需详细了解如何授予角色,请参阅部署权限和管理访问权限。
启用沙盒
任何配置更改都会导致新修订版本的创建。后续修订版本也将自动采用此配置设置,除非您进行了明确更新。
启用沙盒后,您的 Cloud Run 服务会部署在第二代执行环境中。如需在 Cloud Run 服务中启用沙盒,请使用 Google Cloud CLI、YAML 配置或 Terraform:
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
如果您要创建新的服务,请跳过此步骤。如果您要更新现有服务,请下载其 YAML 配置:
gcloud run services describe SERVICE --format export > service.yaml
更新 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格式
使用以下命令创建或更新服务:
gcloud run services replace service.yaml
gcloud run services replace命令默认使用service.yaml文件(如果存在)。
Terraform
如需了解如何应用或移除 Terraform 配置,请参阅基本 Terraform 命令。
将以下内容添加到 Terraform 配置中的google_cloud_run_v2_service 资源:resource "google_cloud_run_v2_service" "default" {
name = "SERVICE"
location = "REGION"
template {
containers {
image = "IMAGE_URL"
sandbox_launcher = true
ports {
container_port = 8080
}
}
}
}
替换以下内容:
- SERVICE:Cloud Run 服务的名称。
- REGION: Google Cloud 区域。例如
europe-west1。 IMAGE_URL:对容器映像的引用,例如us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry,则必须预先创建制品库 REPO_NAME。网址采用LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG格式
沙盒会共享分配给宿主容器的 CPU 和内存。确保主容器的 CPU 和内存限制可以同时容纳应用和您同时运行的任何活跃沙盒。
停用沙盒
如需停用在服务中启动沙盒的功能,请使用 Google Cloud CLI 或 YAML 配置:
gcloud
运行以下命令,使用 --no-sandbox-launcher 标志更新服务:
gcloud beta run services update SERVICE --no-sandbox-launcher
将 SERVICE 替换为服务的名称。
YAML
如果您要创建新的服务,请跳过此步骤。如果您要更新现有服务,请下载其 YAML 配置:
gcloud run services describe SERVICE --format export > service.yaml
更新 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格式
使用以下命令创建或更新服务:
gcloud run services replace service.yaml
gcloud run services replace命令默认使用service.yaml文件(如果存在)。
查看沙盒设置
如需查看 Cloud Run 服务的当前沙盒设置,请执行以下操作:
控制台
在 Google Cloud 控制台中,前往 Cloud Run 服务页面:
点击相应服务,打开其服务详情页面。
点击修订历史记录标签页。
在容器标签页中,找到沙盒启动器设置,查看沙盒容器是处于启用状态还是停用状态。
gcloud
使用以下命令:
gcloud beta run services describe SERVICE
将 SERVICE 替换为服务的名称。
如需验证是否已启用沙盒化容器,请在返回的配置中找到
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 run services describe SERVICE --format export > service.yaml
更新服务 YAML 文件,以包含
sandboxes模板配置:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE annotations: run.googleapis.com/launch-stage: BETA spec: template: spec: containers: - image: IMAGE_URL ports: - containerPort: 8080 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替换以下内容:
- SERVICE: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 run services replace service.yaml
gcloud run services replace命令默认使用service.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/services/SERVICE?updateMask=launchStage,template.containers,template.sandboxes,template.volumes" \ -d '{ "launchStage": "BETA", "template": { "containers": [ { "image": "IMAGE_URL", "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" } } ] } }'
替换以下内容:
- SERVICE: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 运行模板,请参阅使用沙盒模板运行命令。