在 GKE 上啟用 Agent Sandbox

本文說明如何在 Google Kubernetes Engine (GKE) 叢集中啟用 Agent Sandbox 功能，以及如何在叢集上建立沙箱環境，安全地執行不受信任的程式碼。

如要瞭解 Agent Sandbox 功能如何隔離不受信任的 AI 生成程式碼，請參閱「關於 GKE Agent Sandbox」。

費用

在 GKE 中，Agent Sandbox 免費提供，不另外收費。您建立的資源適用 GKE 定價。

為避免產生不必要的費用，請務必在完成本文件後停用 GKE 或刪除專案。

事前準備

  1. 在 Cloud de Confiance 控制台的專案選擇器頁面中，選取或建立 Cloud de Confiance 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
    • 建立專案：如要建立專案，您需要「專案建立者」角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    前往專案選取器

  2. 確認專案已啟用計費功能 Cloud de Confiance 。

  3. 啟用 Artifact Registry 和 Google Kubernetes Engine API。

    啟用 API 時所需的角色

    如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

    啟用 API

  4. 在 Cloud de Confiance 控制台中啟用 Cloud Shell。

    啟用 Cloud Shell

  5. 確認叢集執行的是 GKE 1.35.2-gke.1269000 以上版本。

定義環境變數

為簡化本文中執行的指令，您可以在 Cloud Shell 中設定環境變數。在 Cloud Shell 中執行下列指令，定義下列實用的環境變數：

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export CLUSTER_VERSION="1.35.2-gke.1269000"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"

這些環境變數的說明如下：

  • PROJECT_ID：目前 Cloud de Confiance by S3NS 專案的 ID。定義這個變數可確保所有資源 (例如 GKE 叢集) 都是在正確的專案中建立。
  • CLUSTER_NAME：GKE 叢集的名稱，例如 agent-sandbox-cluster。
  • LOCATION：建立 GKE 叢集的 Cloud de Confiance by S3NS 區域或地帶。如果您建立 Autopilot 叢集，請將此值設為區域 (例如 us-central1)；如果您建立 Standard 叢集，請將此值設為可用區 (例如 us-central1-a)。
  • ：叢集執行的 GKE 版本。Agent Sandbox 功能需要 1.35.2-gke.1269000 以上版本。CLUSTER_VERSION
  • NODE_POOL_NAME：將執行沙箱化工作負載的節點集區名稱，例如 agent-sandbox-pool。只有在建立 GKE Standard 叢集時，才需要這個變數。
  • MACHINE_TYPE：節點集區中節點的機型，例如 e2-standard-2。如要進一步瞭解不同機器系列，以及如何選擇不同選項，請參閱機器家族資源與比較指南。只有在建立 GKE Standard 叢集時，才需要這個變數。

啟用代理程式沙箱

建立新叢集或更新現有叢集時，可以啟用 Agent Sandbox 功能。

建立新的 GKE 叢集時啟用 Agent Sandbox

建議您使用 Autopilot 叢集，享有全代管的 Kubernetes 體驗。如要選擇最適合工作負載的 GKE 作業模式，請參閱「選擇 GKE 作業模式」。

Autopilot

如要建立啟用 Agent Sandbox 的新 GKE Autopilot 叢集，請加入 --enable-agent-sandbox 標記：

gcloud beta container clusters create-auto ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --cluster-version=${CLUSTER_VERSION} \
    --enable-agent-sandbox

如果是 Autopilot 叢集，請確保 LOCATION 環境變數已設為某個區域 (例如 us-central1)。

標準

如要建立啟用 Agent Sandbox 的新 GKE Standard 叢集，請建立叢集、新增啟用 gVisor 的節點集區，然後啟用 Agent Sandbox 功能。為節省費用，建議您建立可用區叢集，每個集區包含一個節點：

  1. 建立叢集：

    gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --cluster-version=${CLUSTER_VERSION}

    針對這個標準叢集，請確認 LOCATION 環境變數已設為區域 (例如 us-central1-a)。

  2. 建立啟用 gVisor 的獨立節點集區：

    gcloud container node-pools create ${NODE_POOL_NAME} \
    --cluster=${CLUSTER_NAME} \
    --machine-type=${MACHINE_TYPE} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --image-type=cos_containerd \
    --sandbox=type=gvisor

    LOCATION 必須與建立叢集時使用的區域相同。

  3. 更新叢集以啟用 Agent Sandbox 功能：

    gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --enable-agent-sandbox

更新現有 GKE 叢集時啟用 Agent Sandbox

如要在現有叢集上啟用 Agent Sandbox，叢集必須執行 1.35.2-gke.1269000 以上版本。

確認 LOCATION 環境變數已設為現有叢集所在的區域或地帶。

  1. 如果您使用 GKE Standard 叢集，Agent Sandbox 會依賴 gVisor。如果 Standard 叢集沒有啟用 gVisor 的節點集區，請先建立一個：

    gcloud container node-pools create ${NODE_POOL_NAME} \
    --cluster=${CLUSTER_NAME} \
    --machine-type=${MACHINE_TYPE} \
    --location=${LOCATION} \
    --image-type=cos_containerd \
    --sandbox=type=gvisor

  2. 更新叢集以啟用 Agent Sandbox 功能：

    gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --enable-agent-sandbox

驗證設定

您可以檢查叢集說明，確認是否已啟用 Agent Sandbox 功能。

gcloud beta container clusters describe ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --format="value(addonsConfig.agentSandboxConfig.enabled)"

如果您建立的是 Autopilot 叢集，位置就是區域 (例如 us-central1)。如果您建立的是 Standard 叢集，位置就是可用區 (例如 us-central1-a)。

如果成功啟用這項功能，指令會傳回 True。

代理程式沙箱部署規定

如要順利部署工作負載 (例如 Sandbox 或 SandboxTemplate)，YAML 資訊清單必須包含特定安全性與設定設定。GKE 會使用驗證許可政策 (VAP) 強制執行這些規定。如果不符合這些規定，許可控制器就會拒絕部署作業。

必要設定

部署資訊清單必須包含下列設定：

  • runtimeClassName: gvisor：確保 Pod 在 gVisor 沙箱中執行。
  • automountServiceAccountToken: false：防止 Pod 自動掛接預設服務帳戶權杖。
  • securityContext.runAsNonRoot: true：確保容器不會以超級使用者身分執行。
  • securityContext.capabilities.drop: ["ALL"]：從容器中捨棄所有 Linux 功能。
  • resources.limits：您必須指定 CPU 和記憶體限制，避免發生潛在的阻斷服務 (DoS) 情境。
  • nodeSelector：必須指定 sandbox.gke.io/runtime: gvisor。
  • tolerations：必須包含 sandbox.gke.io/runtime=gvisor:NoSchedule 汙染的容忍度。

禁止的設定

部署資訊清單不得包含下列任何項目：

  • hostNetwork: true、hostPID: true 或 hostIPC: true。
  • privileged: true 容器安全環境。
  • HostPath 冊。
  • 新增功能 (capabilities.add)。
  • 「hostPort」設定。
  • 自訂 sysctl。
  • 服務帳戶權杖或憑證的預估量。

部署沙箱環境

建議您定義 SandboxTemplate 並使用 SandboxWarmPool 讓預先暖機的執行個體保持就緒狀態，藉此部署沙箱環境。然後，您可以使用 SandboxClaim，從這個暖機節點集區要求執行個體。或者，您也可以直接建立沙箱，但這種做法不支援暖池。

SandboxTemplate、SandboxWarmPool、SandboxClaim 和 Sandbox 都是 Kubernetes 自訂資源。

SandboxTemplate 可做為可重複使用的藍圖。SandboxWarmPool 可確保指定數量的預先暖機 Pod 隨時都在執行，且隨時可供認領。使用這項自訂資源可縮短啟動延遲時間。

如要建立 SandboxTemplate 和 SandboxWarmPool，藉此部署沙箱環境，請完成下列步驟：

  1. 在 Cloud Shell 中，建立名為 sandbox-template.yaml 的檔案，並加入下列內容：

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox-type: python-runtime
    spec:
      runtimeClassName: gvisor # Required
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      restartPolicy: OnFailure

  2. 套用 SandboxTemplate 資訊清單：

    kubectl apply -f sandbox-template.yaml

  3. 建立名為 sandbox-warmpool.yaml 的檔案，並加入以下內容：

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-runtime-warmpool
  namespace: default
  labels:
    app: python-runtime-warmpool
spec:
  replicas: 2
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

  4. 套用 SandboxWarmPool 資訊清單：

    kubectl apply -f sandbox-warmpool.yaml

建立 SandboxClaim

SandboxClaim 會從範本要求沙箱。由於您建立了暖集區，因此建立的沙箱會採用集區中執行的 Pod，而不是啟動新的 Pod。

如要透過建立 SandboxClaim 從範本要求沙箱，請完成下列步驟：

  1. 建立名為 sandbox-claim.yaml 的檔案，並加入以下內容：

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: sandbox-claim
  namespace: default
spec:
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

  2. 套用 SandboxClaim 資訊清單：

    kubectl apply -f sandbox-claim.yaml

  3. 確認沙箱、聲明和暖集區已準備就緒：

    kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod

替代做法：直接建立沙箱

如果您不需要暖集區提供的快速啟動時間，可以直接部署 Sandbox，不必使用範本。

如要直接建立沙箱來部署沙箱環境，請完成下列步驟：

  1. 建立名為 sandbox.yaml 的檔案，並加入以下內容：

    apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-example-2
spec:
  replicas: 1
  podTemplate:
    metadata:
      labels:
        sandbox: sandbox-example
    spec:
      runtimeClassName: gvisor
      restartPolicy: Always
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
        runAsUser: 1000 # Required if image defaults to root (e.g. busybox)
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: my-container
        image: busybox
        command: ["/bin/sh", "-c"]
        args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"]
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
          allowPrivilegeEscalation: false
        resources:
          limits:
            cpu: "100m"
            memory: "128Mi" # Required

  2. 套用 Sandbox 資訊清單：

    kubectl apply -f sandbox.yaml

  3. 確認沙箱正在執行：

    kubectl get sandbox

停用 Agent Sandbox

如要停用 Agent Sandbox 功能，請使用 gcloud beta container clusters update 指令搭配 --no-enable-agent-sandbox 旗標。

gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --no-enable-agent-sandbox

如果您建立的是 Autopilot 叢集，位置就是區域 (例如 us-central1)。如果您建立的是 Standard 叢集，位置就是可用區 (例如 us-central1-a)。

清除所用資源

如要避免系統向您的 Cloud de Confiance by S3NS 帳戶收取費用，請刪除您建立的 GKE 叢集。

gcloud container clusters delete $CLUSTER_NAME \
    --location=${LOCATION} \
    --quiet

如果您建立的是 Autopilot 叢集，位置就是區域 (例如 us-central1)。如果您建立的是 Standard 叢集，位置就是可用區 (例如 us-central1-a)。

後續步驟