使用 Agent Sandbox 隔離 AI 程式碼執行作業

本文說明如何在 Google Kubernetes Engine (GKE) 叢集上部署開發人員環境，並使用 Agent Sandbox Python 用戶端。

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

費用

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

事前準備

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

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

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

    前往專案選取器

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

  3. 啟用 Artifact Registry 和 Kubernetes Engine API。

    啟用 API 時所需的角色

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

    啟用 API

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

    啟用 Cloud Shell

  5. 確認您具備完成本指南所需的權限。
  6. 您必須擁有已啟用 Agent Sandbox 功能的 GKE 叢集。如果沒有，請按照「在 GKE 上啟用 Agent Sandbox」一文的操作說明，建立新叢集或更新現有叢集。

必要的角色

如要取得建立及管理沙箱所需的權限，請要求管理員授予您專案的 Kubernetes Engine 管理員 (roles/container.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

定義環境變數

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

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

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

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

部署沙箱環境

本節說明如何建立沙箱藍圖 (SandboxTemplate)、部署必要的網路路由器，以及安裝用於與沙箱互動的 Python 用戶端。

建議使用 Agentic Sandbox Python 用戶端建立沙箱並與之互動。這個用戶端提供介面，可簡化沙箱的整個生命週期，從建立到清除都適用。這個 Python 程式庫可讓您透過程式建立、使用及刪除沙箱。

用戶端會使用 Sandbox Router 做為所有流量的中央進入點。在本文件所述的範例中，用戶端會使用 kubectl port-forward 指令建立通往這個路由器的通道，因此您不需要公開任何公開 IP 位址。請注意，使用 kubectl port-forward 並非安全解決方案，因此應僅限於開發環境。

建立 SandboxTemplate 和 SandboxWarmPool

現在，請建立 SandboxTemplate 和 SandboxWarmPool 資源，定義沙箱的設定。SandboxTemplate 可做為可重複使用的藍圖，Agent Sandbox 控制器會使用這份藍圖建立一致的預先設定沙箱環境。SandboxWarmPool 資源可確保指定數量的預先暖機 Pod 隨時都在執行中，且隨時可供使用。預先暖機的沙箱是已初始化的執行中 Pod。這項預先初始化作業可讓您在不到一秒內建立新的沙箱，並避免啟動一般沙箱時發生啟動延遲：

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

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      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: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template

  2. 套用 SandboxTemplate 和 SandboxWarmPool 資訊清單：

    kubectl apply -f sandbox-template-and-pool.yaml

部署沙箱路由器

您將用來建立沙箱環境並與之互動的 Python 用戶端，會使用名為「沙箱路由器」的元件與沙箱通訊。

在本範例中，您會使用用戶端的開發人員模式進行測試。這個模式適用於本機開發，並使用 kubectl port-forward 指令，在本機與叢集中執行的 Sandbox Router 服務之間建立直接通道。這種通道方法不需要公開 IP 位址或複雜的輸入設定，可簡化從本機環境與沙箱互動的程序。

請按照下列步驟部署 Sandbox Router：

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

    # A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:latest-main
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "100m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

  2. 套用資訊清單，將路由器部署至叢集：

    kubectl apply -f sandbox-router.yaml

  3. 確認沙箱路由器部署作業正常運作：

    kubectl get deployment sandbox-router-deployment

    等待部署作業在 READY 欄中顯示 2/2 或 1/1。

安裝 Python 用戶端

現在已部署 Sandbox 路由器等叢集內元件，最後一個準備步驟是在本機安裝 Agentic Sandbox Python 用戶端。請注意，這個用戶端是 Python 程式庫，可讓您以程式輔助方式建立、使用及刪除沙箱。您會在下一節中使用這個檔案測試環境：

  1. 建立並啟用 Python 虛擬環境：

    python3 -m venv .venv
source .venv/bin/activate

  2. 安裝用戶端套件：

    pip install k8s-agent-sandbox

測試沙箱

完成所有設定元件後，您現在可以使用 Agentic Sandbox Python 用戶端建立沙箱並與之互動。

  1. 在 agent-sandbox 目錄中，建立名為 test_sandbox.py 的 Python 指令碼，並加入以下內容：

    from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

# Automatically tunnels to svc/sandbox-router-svc
client = SandboxClient(
    connection_config=SandboxLocalTunnelConnectionConfig()
)

sandbox = client.create_sandbox(template="python-runtime-template", namespace="default")
try:
    print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  2. 在終端機中 (虛擬環境仍處於啟用狀態)，執行測試指令碼：

    python3 test_sandbox.py

您應該會看到「Hello from the sandboxed environment!」訊息，這是沙箱的輸出內容。

恭喜！您已在安全沙箱中成功執行殼層指令。使用 sandbox.run() 方法，您可以執行任何殼層指令，而 Agent Sandbox 會在安全屏障內執行指令，保護叢集節點和其他工作負載免於不受信任的程式碼侵害。這為 AI 代理或任何自動化工作流程提供安全可靠的任務執行方式。

執行指令碼時，SandboxClient 會為您處理所有步驟。這個指令會建立 SandboxClaim 資源來啟動沙箱、等待沙箱準備就緒，然後使用 sandbox.run() 方法在安全容器內執行 Bash 殼層指令。接著，用戶端會擷取並列印該指令的 stdout。程式執行完畢後，沙箱會自動刪除。

建立 SandboxClaim 資源時，系統會從暖池將可用的 Pod 指派給 Sandbox 物件，並將聲明標示為就緒。SandboxWarmPool 接著會自動補充，以維持設定的副本數量。

如要確認特定沙箱是否已聲明或可用，請檢查沙箱 Pod 中繼資料中的 ownerReferences，如果 kind 欄位的值為 Sandbox，表示該 Pod 正在使用中。如果 kind 欄位的值為 SandboxWarmPool，表示 Pod 處於閒置狀態，等待認領。

在正式環境中執行沙箱

在本文件中，您將使用 Cloud Shell，從叢集外部與沙箱互動。Python 用戶端會使用您的使用者憑證向叢集進行驗證，並管理沙箱資源，還會使用 kubectl port-forward 指令與沙箱建立連線。這些步驟適用於開發情境。

在正式環境中，控制器應用程式 (例如 AI 自動調度管理工具) 負責建立及管理沙箱資源。如要在正式環境中使用 Agent Sandbox，請考慮下列事項：

  • 驗證：您的控制器應用程式必須向叢集 API 伺服器驗證，才能執行沙箱。驗證設定方式取決於控制器應用程式的執行位置，如下所示：

    • 如果控制器應用程式在同一個叢集中以 Pod 形式執行，請使用 Kubernetes RBAC 或 Workload Identity Federation for GKE搭配 IAM 政策，授予 Pod 的 Kubernetes ServiceAccount 監控沙箱或探索網路端點所需的權限。
    • 如果控制器應用程式在叢集外部執行，請使用工作負載身分聯盟或 IAM 服務帳戶，為應用程式提供身分，以便在允許政策中參照。

  • 轉送：來自控制器應用程式中 Python 用戶端的要求，必須送達叢集中的 Sandbox 路由器。在實際工作環境中，請使用下列其中一種方法建立網路連線：

    • 如果控制器應用程式在同一個叢集中執行，請使用 SandboxDirectConnectionConfig 函式，指定 Sandbox Router 服務使用的網址和通訊埠。
    • 如果控制器應用程式在叢集外部執行，請使用 GKE Gateway API 建立內部或外部負載平衡器。在用戶端程式碼中，使用 SandboxGatewayConnectionConfig 函式參照 Gateway。

    如要進一步瞭解這些轉送方法，請參閱 GitHub 上的使用範例和路由器的閘道部署步驟。

  • 存取沙箱資源 Google Cloud ：如果沙箱程式碼需要向 Cloud Storage 等 Google Cloud API 傳送要求，請使用具有 Workload Identity Federation for GKE 的 IAM 政策，授予沙箱 Pod 使用的 Kubernetes ServiceAccount 存取權，以便存取資源。

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收費，請刪除您建立的 GKE 叢集：

gcloud container clusters delete $CLUSTER_NAME --location=$LOCATION --quiet

後續步驟