設定服務的沙箱

Cloud Run 沙箱提供快速、安全且隔離的環境,可在第二代環境的現有服務中,執行不受信任的程式碼或執行工具 (例如 AI 代理)。沙箱經過高度最佳化,可降低延遲,並在與容器相同的執行個體中執行,共用分配的 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 服務。

必要的角色

如要取得設定及部署 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 設定或 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

  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

    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

  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

    gcloud run services replace 指令預設會使用 service.yaml 檔案 (如有)。

查看沙箱設定

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

控制台

  1. 在 Google Cloud 控制台中,前往 Cloud Run 的「Services」(服務) 頁面:

    前往 Cloud Run。

  2. 按一下服務,開啟「Service details」(服務詳細資料) 頁面。

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

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

gcloud

  1. 使用下列指令:

    gcloud beta run services describe SERVICE

    將 SERVICE 改為您的服務名稱。

  2. 如要確認沙箱容器已啟用,請在傳回的設定中找出 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) 會從範本產生新的沙箱容器,無須佈建新的 VM,也不會產生新執行個體的費用。

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

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

YAML

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

    gcloud run services describe SERVICE --format export > service.yaml
  2. 更新服務 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。
  3. 使用下列指令建立或更新服務:

    gcloud run services replace service.yaml

    gcloud run services replace 指令預設會使用 service.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/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 執行範本,請參閱「使用沙箱範本執行指令」。