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

您可以部署開發人員環境，在 Google Kubernetes Engine (GKE) 叢集上使用 Agent Sandbox Python 用戶端。這項設定可將不受信任的程式碼隔離在沙箱 Python 環境中，安全地執行及測試 AI 生成的程式碼。這種隔離措施對於保護系統免於 AI 生成程式碼中的潛在安全漏洞、提高開發速度，以及確保安全部署至關重要。如要概略瞭解 GKE 的 Agent Sandbox 如何隔離不受信任的 AI 生成程式碼，請參閱「關於 GKE 的 Agent Sandbox」。

費用

GKE 的 Agent Sandbox 無須額外付費。您建立的資源適用 GKE 定價。

事前準備

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

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

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

   前往專案選取器

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

3. 啟用 Artifact Registry 和 Kubernetes Engine API (如果尚未啟用)。

   啟用 API 所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   啟用 API

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

   啟用 Cloud Shell

5. 確認您具備所需的權限，可完成本文件中的操作。
6. 您必須擁有已啟用 GKE Agent Sandbox 的 GKE 叢集。如果沒有，請按照「在 GKE 啟用代理程式沙箱」中的操作說明，建立新叢集或更新現有叢集。

必要的角色

如要取得建立及管理沙箱所需的權限，請要求管理員授予您專案的 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：目前 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)。
• NODE_POOL_NAME：要執行沙箱化工作負載的節點集區名稱，例如 agent-sandbox-node-pool。
• MACHINE_TYPE：節點集區中節點的機型，例如 e2-standard-2。如要進一步瞭解不同的機器系列，以及如何選擇不同選項，請參閱「機器家族資源與比較指南」。

部署沙箱環境

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

建議使用 Agentic Sandbox Python 用戶端建立沙箱並與其互動。這個用戶端提供的介面可簡化沙箱的整個生命週期，從建立到清理都涵蓋在內。這個 Python 程式庫可供您以程式輔助方式建立、使用及刪除沙箱。

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

建立 SandboxTemplate 和 SandboxWarmPool

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

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

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   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/v1beta1
   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. 確認 Sandbox Router 部署作業正常運作：

   kubectl get deployment sandbox-router-deployment
   

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

安裝 Python 用戶端

部署 Sandbox Router 等叢集內元件後，最後一項準備步驟是在本機電腦上安裝 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() 方法，您可以執行任何殼層指令，而 GKE 上的 Agent Sandbox 會在安全屏障內執行指令，保護叢集的節點和其他工作負載，不受不受信任的程式碼影響。這項功能可讓 AI 代理程式或任何自動化工作流程安全可靠地執行工作。

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

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

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

在正式環境中執行沙箱

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

在正式環境中，控制器應用程式 (例如 AI 協調器) 負責建立及管理沙箱資源。如要在正式環境中使用 GKE 上的 Agent Sandbox，請考量下列事項：

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

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

• 轉送：控制器應用程式中 Python 用戶端的要求，必須傳送至叢集中的沙箱路由器。在正式環境中，請使用下列其中一種方法建立網路連線：

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

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

• 沙箱存取 Cloud de Confiance 資源：如果沙箱程式碼需要傳送要求至 Cloud de Confiance API (例如 Cloud Storage)，請使用 IAM 政策搭配 GKE 適用的 Workload Identity Federation，將該存取權所需的權限，授予沙箱 Pod 使用的 Kubernetes ServiceAccount。由於預設網路政策會封鎖對 Cloud de Confiance by S3NS 中繼資料伺服器 (169.254.169.254) 的存取，因此您必須自訂網路政策，允許這類流量。

• 網路政策限制：根據預設，GKE 上的 Agent Sandbox 會強制執行嚴格的「預設安全」網路狀態 (networkPolicyManagement: Managed)。在這種狀態下，適用下列限制：

  • 除了指定的 Sandbox 路由器，所有來源的連入都會遭到封鎖。
  • 輸出可連線至公開網際網路，但會明確封鎖輸出至私人 LAN 範圍 (RFC 1918)、內部叢集 DNS (CoreDNS) 和 Cloud Provider Metadata Server (169.254.0.0/16)。

  如要使用 Workload Identity Federation for GKE 或存取其他私人資源，您必須在 SandboxTemplate 中定義自訂網路政策。如需詳細設定資訊和可自訂的範本 (例如無網路連線的沙箱或 GKE 整合的 Workload Identity Federation)，請參閱「代理程式沙箱網路政策管理」。

沙盒安全政策

為確保預設安全環境，GKE 外掛程式的 Agent Sandbox 會使用 Kubernetes 驗證許可政策 (VAP)，對 Sandbox 和 SandboxTemplate 資源強制執行安全限制。系統會自動套用這些政策。

此外掛程式將安全防護措施分為兩層政策模型，更具彈性。以下各節將說明這些政策：嚴格管理的核心政策和可自訂的強化政策。

核心安全性政策 (sandbox-core-policy)

核心安全性政策會強制執行隔離規定，協助保護沙箱的完整性。這項政策包含多項規則，例如要求使用 gVisor、停用 hostNetwork 等網路隔離措施，以及封鎖 hostPath 等檔案系統隔離措施。GKE 會透過 addonmanager.kubernetes.io/mode: Reconcile 設定管理這項政策，因此您無法修改或覆寫這些核心規則。

強化安全性政策 (sandbox-hardening-policy)

強化安全性政策提供額外的安全性最佳做法和管理選項。這項政策會強制執行限制，例如捨棄所有功能、禁止新增功能，以及要求容器以非 root 身分執行，並限制資源。GKE 會透過 addonmanager.kubernetes.io/mode: EnsureExists 設定，以EnsureExists模式部署這項政策。這項設定代表 GKE 會在政策遺失時建立政策，但您仍可視需要修改或刪除政策或其繫結。

修改或移除強化限制

由於安全強化政策是以 EnsureExists 模式部署，因此 GKE 會在政策遺失時建立政策，但不會覆寫您的修改內容。如果工作負載需要豁免這些強化規則，您可以修改政策，移除特定限制或完全刪除政策繫結。

如要修改強化政策並移除特定限制 (例如允許容器以根身分執行，或省略資源限制)，請編輯 ValidatingAdmissionPolicy 資源：

kubectl edit validatingadmissionpolicy sandbox-hardening-policy

在開啟的文字編輯器中，找出 validations 區段，然後移除或修改會封鎖工作負載的限制運算式。

或者，如要完全停用叢集的強化政策，請刪除政策繫結：

kubectl delete validatingadmissionpolicybinding sandbox-hardening-binding

已知問題

本節說明在 GKE 上使用 Agent Sandbox 時的已知問題，以及如何解決或規避這些問題。

使用服務網格時，安全性政策會封鎖功能

如果您嘗試部署與服務網格 Sidecar (例如 Envoy 或 Istio) 整合的沙箱，強化安全政策可能會封鎖沙箱建立作業，並顯示類似下列的錯誤訊息：

sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'sandbox-hardening-policy' with binding 'sandbox-hardening-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.

• 原因：服務網格 Sidecar 通常會使用 init 容器，例如 istio-init 或 proxy-init。這些 init 容器需要 NET_ADMIN 或 NET_RAW 等功能，才能設定 iptables 規則，以進行透明輸出路由。根據預設，GKE sandbox-hardening-policy會封鎖所有容器類型中的所有功能新增項目。
• 解決方法：由於 GKE 強化政策是以 EnsureExists 模式部署，您可以修改 ValidatingAdmissionPolicy，允許特定受信任的 init 容器要求 NET_ADMIN 和 NET_RAW 功能。如要瞭解如何修改或移除這些強化限制，請參閱「修改或移除強化限制」。舉例來說，您可以更新政策的驗證運算式或變數，從功能規則中排除信任的容器名稱。

透過 IPv6 連線至 Google API 時，輸出延遲或逾時

沙箱中的工作負載嘗試連線至外部資源或 Google API (例如 Vertex AI 或 Cloud Storage) 時，可能會發生連線逾時或高延遲 (最多兩分鐘) 的情況。

• 原因：如果 GKE 叢集啟用雙重堆疊 IPv6，Google API 的 DNS 解析會同時傳回 IPv4 (A) 和 IPv6 (AAAA) 位址。執行階段引擎 (例如 Node.js) 中的某些演算法會先嘗試透過 IPv6 連線。如果 GKE 虛擬私有雲沒有有效的 IPv6 egress 路由，例如 Cloud NAT 或 IPv6 網際網路閘道，TCP 連線會停止回應，直到 TCP SYN 逾時。然後 TCP 連線會回復為 IPv4。

• 解決方法：如要解決這個問題，請按照下列其中一種做法進行：

  • 設定 IPv6 輸出：如要允許傳出 IPv6 流量傳回叢集，請在虛擬私有雲網路中設定有效的 IPv6 Cloud NAT 或網際網路閘道。

  • 在工作負載中偏好使用 IPv4：如要偏好使用 IPv4 DNS 解析，請設定工作負載的執行階段。舉例來說，在 Node.js 應用程式中，您可以在 SandboxTemplate 定義中設定下列環境變數：

    env:
    - name: NODE_OPTIONS
      value: "--dns-result-order=ipv4first --no-network-family-autoselection"
    

清除所用資源

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

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

後續步驟

• 瞭解如何使用 Pod 快照在 GKE 環境中儲存及還原 Agent Sandbox。
• 如要進一步瞭解 Agent Sandbox 開放原始碼專案，請前往 GitHub。
• 瞭解如何在 GKE 上搭配使用開放原始碼 Kata Containers 和 Agent Sandbox。Kata Containers 不是 Cloud de Confiance 產品，如果您安裝並使用這類軟體，就必須負責管理及排解問題。Google 的支援和服務水準協議不適用於 Kata Containers。
• 如要瞭解為工作負載提供安全隔離的基礎技術，請參閱「GKE Sandbox」。
• 如要進一步瞭解如何強化叢集和工作負載的安全性，請參閱「GKE 安全性總覽」。