設定工作站集區的沙箱

Cloud Run 沙箱提供快速、安全且隔離的環境,可在 worker 集區中執行 Agentic Workflows、執行不受信任的酬載,以及隔離處理事件。沙箱經過高度最佳化,可降低延遲時間,並在與容器相同的執行個體中執行,共用分配的 CPU 和記憶體。

本頁說明如何在容器上設定沙箱。如要進一步瞭解如何編寫程式碼,以便使用 CLI 與沙箱互動,請參閱「在 Cloud Run 中執行程式碼」。

事前準備

  1. 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

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

  3. 安裝並初始化 gcloud CLI。
  4. 部署 Cloud Run worker 集區。

必要的角色

如要取得設定及部署 Cloud Run worker 集區所需的權限,請要求管理員授予您下列 IAM 角色:

如要查看與 Cloud Run 相關聯的 IAM 角色和權限清單,請參閱「Cloud Run IAM 角色」和「Cloud Run IAM 權限」。如果 Cloud Run worker 集區與Google Cloud API (例如 Cloud 用戶端程式庫) 介接,請參閱服務身分設定指南。如要進一步瞭解如何授予角色,請參閱「部署權限」和「管理存取權」。

啟用沙箱

任何設定變更都會建立新的修訂版本。除非您明確更新設定,否則後續修訂版本也會自動套用這項設定。

如要在 Cloud Run worker 集區啟用沙箱,請使用 Google Cloud CLI、YAML 設定或 Terraform:

gcloud

如要部署或更新 worker 集區,請指定 --sandbox-launcher 旗標:

  • 如要部署新的 worker 集區,請執行下列指令:

    gcloud beta run worker-pools deploy WORKER_POOL --image IMAGE_URL --sandbox-launcher

    更改下列內容:

    • WORKER_POOL:Cloud Run worker 集區的名稱。
    • IMAGE_URL:參照含有 worker 集區的容器映像檔,例如 us-docker.pkg.dev/cloudrun/container/worker-pool:latest
  • 如要更新現有的 worker 集區,請執行下列指令:

    gcloud beta run worker-pools update WORKER_POOL --sandbox-launcher

YAML

  1. 如要建立新的 worker 集區,請略過這個步驟。如要更新現有 worker 集區,請下載其 YAML 設定:

    gcloud run worker-pools describe WORKER_POOL --format export > worker-pool.yaml
  2. 更新 YAML 檔案,在容器設定中加入設為 true 的 sandboxLauncher 屬性:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
      name: WORKER_POOL
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        spec:
          containers:
          - name: CONTAINER
            image: IMAGE_URL
            sandboxLauncher: true
    

    更改下列內容:

    • WORKER_POOL:Cloud Run worker 集區的名稱。
    • CONTAINER:容器名稱。
    • IMAGE_URL:參照含有 worker 集區的容器映像檔,例如 us-docker.pkg.dev/cloudrun/container/worker-pool:latest
  3. 使用下列指令建立或更新 worker 集區:

    gcloud run worker-pools replace worker-pool.yaml

    gcloud run worker-pools replace 指令預設會使用 worker-pool.yaml 檔案 (如有)。

Terraform

如要瞭解如何套用或移除 Terraform 設定,請參閱「基本 Terraform 指令」。

resource "google_cloud_run_v2_worker_pool" "default" {
  name     = "WORKER_POOL"
  location = "REGION"

  template {
    containers {
      image            = "IMAGE_URL"
      sandbox_launcher = true
    }
  }
}

更改下列內容:

  • WORKER_POOL:Cloud Run worker 集區的名稱。
  • REGION: Google Cloud 區域。例如:europe-west1。
  • IMAGE_URL:參照含有 worker 集區的容器映像檔,例如 us-docker.pkg.dev/cloudrun/container/worker-pool:latest

沙箱會共用分配給主機容器的 CPU 和記憶體配置。請確認主要容器的 CPU 和記憶體限制,可同時容納應用程式和任何執行中的沙箱。

停用沙箱

如要停用在 worker 集區中啟動沙箱的功能,請使用 Google Cloud CLI 或 YAML 設定:

gcloud

執行下列指令,使用 --no-sandbox-launcher 旗標更新 worker 集區:

gcloud beta run worker-pools update WORKER_POOL --no-sandbox-launcher

將 WORKER_POOL 替換為 worker 集區名稱。

YAML

  1. 如要建立新的 worker 集區,請略過這個步驟。如要更新現有 worker 集區,請下載其 YAML 設定:

    gcloud run worker-pools describe WORKER_POOL --format export > worker-pool.yaml
  2. 更新 YAML 檔案,移除容器設定中的 sandboxLauncher 屬性:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
      name: WORKER_POOL
    spec:
      template:
        spec:
          containers:
          - name: CONTAINER
            image: IMAGE_URL
    

    更改下列內容:

    • WORKER_POOL:Cloud Run worker 集區的名稱。
    • CONTAINER:容器名稱。
    • IMAGE_URL:參照含有 worker 集區的容器映像檔,例如 us-docker.pkg.dev/cloudrun/container/worker-pool:latest
  3. 使用下列指令建立或更新 worker 集區:

    gcloud run worker-pools replace worker-pool.yaml

    gcloud run worker-pools replace 指令預設會使用 worker-pool.yaml 檔案 (如有)。

查看沙箱設定

如要查看 Cloud Run worker 集區目前的沙箱設定,請按照下列步驟操作:

控制台

  1. 前往 Google Cloud 控制台的 Cloud Run「Worker pools」(工作站集區) 頁面:

    前往 Cloud Run worker 集區

  2. 按一下 worker 集區,開啟「Worker pools details」(Worker 集區詳細資料) 頁面。

  3. 點選「修訂版本」分頁標籤。

  4. 在「容器」分頁中,找到「沙箱啟動器」設定,查看沙箱容器是否已啟用。

gcloud

  1. 使用下列指令:

    gcloud run worker-pools describe WORKER_POOL

    將 WORKER_POOL 替換為 worker 集區名稱。

  2. 如要確認沙箱容器已啟用,請在傳回的設定中找出 sandboxLauncher: true 屬性。

如要在 worker 集區的沙箱中執行不受信任的程式碼,請參閱「在 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) 會從範本產生新的沙箱容器,無須佈建新的 VM,也不會產生新執行個體的費用。

  • 每個沙箱獨立共用檔案:在主要容器和多個沙箱之間共用記憶體內磁碟區,同時限制每個沙箱只能存取自己的獨立子目錄,防止沙箱查看或修改其他檔案。

您可以使用 YAML 設定或 Cloud Run Admin API 設定沙箱範本:

YAML

  1. 如要建立新的 worker 集區,請略過這個步驟。如要更新現有 worker 集區,請下載其 YAML 設定:

    gcloud run worker-pools describe WORKER_POOL --format export > worker-pool.yaml
  2. 更新 worker 集區 YAML 檔案,加入 sandboxes 範本設定:

    apiVersion: run.googleapis.com/v1
    kind: WorkerPool
    metadata:
      name: WORKER_POOL
      labels:
        cloud.googleapis.com/location: REGION
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        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
    

    更改下列內容:

    • WORKER_POOL:Cloud Run worker 集區的名稱。
    • REGION: Google Cloud 區域。例如:europe-west1。

    • 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。
  3. 使用下列指令建立或更新 worker 集區:

    gcloud run worker-pools replace worker-pool.yaml

    gcloud run worker-pools replace 指令預設會使用 worker-pool.yaml 檔案 (如有)。

REST API

如要設定沙箱範本,請將 PATCH 要求傳送至 Cloud Run Admin API:

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/workerPools/WORKER_POOL?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"
        }
      }
    ]
  }
}'

更改下列內容:

  • WORKER_POOL:Cloud Run worker 集區的名稱。

  • 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。

如要透過 worker 集區容器使用 CLI 執行範本,請參閱「使用沙箱範本執行指令」。