設定服務的沙箱

Cloud Run 沙箱提供快速、安全且隔離的環境，可在第二代環境的現有服務中執行不受信任的程式碼或工具，例如 AI 代理。沙箱經過高度最佳化，可降低延遲，並與容器在同一個執行個體中執行，共用分配到的 CPU 和記憶體。

本頁面說明如何在容器中設定沙箱。如要瞭解如何編寫程式碼，透過 CLI 與沙箱互動，請參閱「在 Cloud Run 中執行程式碼」。

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  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 檔案，在容器設定中加入 sandboxLauncher 屬性，並將其設為 true：

    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()

Sandbox CLI

如要直接從指令列執行沙箱指令，請執行下列指令：

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

本指南中的範例使用 sandbox 指令，而非絕對路徑 /usr/local/gcp/bin/sandbox。

如要查看可用指令的完整清單，請執行 /usr/local/gcp/bin/sandbox -h 指令。

如要從服務在沙箱中執行不受信任的程式碼，請參閱「在 Cloud Run 中執行程式碼」。