在 GKE 上使用 Agent Sandbox 自動評估程式碼

1. 簡介

在本程式碼研究室中，您將在 Google Kubernetes Engine (GKE) 上部署 Hackathon Judge 應用程式，並使用 Kubernetes-sigs Agent Sandbox 安全地執行代理工作負載。

這個平台旨在透過 LLM 代理程式，自動化審查、測試及評分黑客松專案的程序。由於評估作業需要評估不受信任的參與者程式碼提交內容，因此安全執行沙箱對於防止程式碼注入、提權或資源濫用至關重要。

學習內容

• 佈建目標 Google Cloud 服務，並建立目標 API。
• 初始化 GKE Autopilot，並安裝 Agent Sandbox CRD、叢集設定和 Sandbox Router。
• 部署沙箱閘道、沙箱聲明範本和沙箱 WarmPool。
• 部署 REST 後端 API、ADK 評分工作人員代理程式和 React 前端 UI。
• 連結外部負載平衡路由，並存取平台，執行安全無虞的沙箱評審工作流程。

軟硬體需求

• 網路瀏覽器，例如 Chrome。
• 已啟用計費功能的 Google Cloud 專案。

在本程式碼研究室中建立的資源，在執行階段產生的總費用應低於 $5 美元。

2. 問題：安全地評估不受信任的程式碼

黑客松是步調快速的創新活動，參與者會建構並提交專案 (通常包括原始碼) 以供評估。手動判斷這些提交內容非常耗時且耗資源。使用 AI 代理程式自動評分是很有前景的解決方案，但會帶來重大安全挑戰：如何安全地執行參與者提供的程式碼 (可能含有錯誤、惡意內容或耗用大量資源)？

直接在基礎架構上執行不受信任的程式碼，會導致下列風險：

• 程式碼注入：惡意指令碼可能會嘗試存取或修改私密資料。
• 權限提升：程式碼可能會嘗試未經授權存取其他系統或網路資源。
• 資源濫用：程式碼編寫不當或遭受阻斷服務攻擊，可能會耗用過多 CPU、記憶體或網路頻寬，進而影響其他作業。

如要使用 AI 自動評估黑客松作品，我們需要一種方法，在與系統其餘部分和其他提交內容完全隔離的環境中執行提交的程式碼。

3. 解決方案：GKE Agent Sandbox

GKE Agent Sandbox 專為解決這項挑戰而設計。這項功能有助於管理 GKE 上獨立、具狀態且單一副本的工作負載，並針對 AI 代理執行階段等用途進行最佳化，確保不信任的程式碼能安全且有效率地執行。

Agent Sandbox 的主要優點包括：

• 核心層級隔離：使用 gVisor 等技術，為不受信任的程式碼提供強大的核心層級隔離機制，防止程式碼存取主機系統或其他容器。
• 秒級佈建：可快速佈建沙箱環境 (通常不到 1 秒)，這對隨選程式碼評估至關重要。
• 雲端原生擴充性：充分運用 Kubernetes 的強大功能和 GKE 的代管基礎架構。

使用 Agent Sandbox，我們可以為每項黑客松提交內容建立隨選的獨立環境。接著，AI 評估代理程式就能指示代理程式沙箱在這個安全沙箱中執行測試、編譯程式碼，或執行其他評估步驟，而不會影響整體平台的完整性。這項功能可擴充、安全且有效率，有助於自動評分黑客松。

4. 事前準備

啟動 Cloud Shell

點選下方按鈕啟動 Google Cloud Shell，其中已預先設定必要的開發人員和雲端指令列公用程式。

啟動 Cloud Shell

啟用 API

在 Cloud Shell 中執行下列指令，啟用執行平台所需的所有目標 Google Cloud API：

gcloud services enable \
  container.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  pubsub.googleapis.com \
  aiplatform.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  bigquery.googleapis.com \
  bigqueryconnection.googleapis.com

啟用這些 API 的原因：Google Cloud 服務預設為停用，可防止未經授權的存取和費用。我們啟用這些特定 API，以啟動容器協調 (GKE)、安全容器儲存空間 (Artifact Registry)、無伺服器建構封裝 (Cloud Build)、可靠的訊息佇列 (Pub/Sub)、AI 模型服務 (Vertex AI)、專案設定 (Cloud Resource Manager 和 IAM)、無伺服器資料分析 (BigQuery)，以及資料庫層級的 AI 繫結 (BigQuery Connection)。

5. 設定基礎架構

在這個步驟中，您將複製程式碼存放區，並執行自動設定指令碼，部署目標雲端架構和基準叢集元件。

複製存放區

複製存放區，當中包含所有應用程式服務、設定指令碼和 Kubernetes 資訊清單宣告：

git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set codelabs/ai-toolkit-lab-2/hackathon-judge
cd codelabs/ai-toolkit-lab-2/hackathon-judge

執行部署指令碼

deploy.sh 指令碼會自動完成雲端資源、資料庫模型和基準 Kubernetes 叢集政策的基礎設定。

執行指令碼：

./deploy.sh

按照互動式殼層提示提供設定，例如有效專案 ID 和目標區域。這個指令碼會自動產生本機 .env 設定、繫結資源、編譯容器映像檔，以及註冊 GKE 基準基礎架構。

指令碼執行的目標作業如下：

1. 設定環境設定

指令碼會建立 .env 設定檔，用來儲存 GKE、Pub/Sub、BigQuery 和專案變數參數。動態取得這個檔案，即可填入後續所有 Kubernetes 資訊清單定義。

設定這個環境檔案的原因：.env 檔案會集中管理設定參數，確保我們在後續步驟中手動套用的 GKE 資訊清單使用相同的區域設定、專案名稱和資源，嚴格將環境設定與原始碼分離。

2. Google Cloud CLI 和目標專案設定

這個指令碼會驗證 gcloud、bq、kubectl 和 envsubst 公用程式是否已安裝、檢查驗證狀態，並將有效設定目標鎖定在有效 Google Cloud 雲端專案上。

為何要指定有效專案：設定有效目標專案可防止 CLI 指令影響帳戶中的其他專案，並執行預先驗證檢查，確保設定指令不會因憑證無效而在部署期間失敗。

3. 啟用目標 Google Cloud API

指令碼會執行等冪檢查，驗證並啟用目標 Google Cloud 服務 API (GKE、Artifact Registry、Cloud Build、Pub/Sub、Vertex AI、BigQuery 和 IAM)。

啟用 Google Cloud API 的原因：必須先啟用受管理雲端服務，才能連上端點或建立資源。在開始時啟用這些 API，可讓地區 GCP API 閘道準備好處理後續的資源佈建指令。

4. 佈建 Artifact Registry Docker 存放區

指令碼會在選取的目標位置，佈建名為 hackathon-judge-repo 的 Docker 容器存放區。

建立 Artifact Registry 存放區的原因：GKE 叢集需要安全存取相同區域網路中的私人容器登錄檔，才能快速提取應用程式映像檔。Artifact Registry 提供安全私密的主機，可編目、掃描及儲存 Docker 容器映像檔。

5. 佈建 GKE Autopilot 叢集

這個指令碼會佈建名為 hackathon-judge-cluster 的 Google Kubernetes Engine (GKE) Autopilot 叢集。

我們部署 GKE Autopilot 叢集的原因：GKE Autopilot 會自動管理節點佈建、資源調度、健康狀態監控和主機 OS 安全性升級。這個平台提供正式環境等級的容器平台，可協調處理持續性服務，並視需要動態排程安全工作人員沙箱。

6. 設定 Pub/Sub 主題和訂閱項目

指令碼會佈建訊息主題 (judging-tasks 和 judging-results)，以及對應的工作人員和 API 訂閱項目。

我們部署 Pub/Sub 主題和訂閱項目的原因：評估提交的程式碼既緩慢又耗用大量資源。使用訊息佇列架構可將同步使用者面向的 API 與工作站節點分離。API 後端會將工作推送至 judging-tasks 主題，工作人員代理程式則會在工作可用時提取，避免 API 遭到封鎖，並提供自動重試功能。

7. 設定 BigQuery 資料集、資料表和 AI 連線

這個指令碼會建立 hackathon_judge 資料集、套用結構化 SQL 資料庫結構定義、載入種子記錄，並將必要的 AI 和儲存空間角色授予 BigQuery ML 連線服務帳戶。

8. 使用 Cloud Build 觸發容器建構作業

指令碼會觸發 cloudbuild.yaml 定義，編譯 React UI、Go REST 伺服器、Python ADK 工作站和 FastAPI 沙箱，將這些項目封裝到標記為有效存放區 Git 提交 SHA 的獨立容器映像檔，並儲存至 Artifact Registry。

9. 註冊 Agent Sandbox 自訂資源定義 (CRD)

這個指令碼會下載並註冊最新的 Kubernetes-sigs Agent Sandbox 自訂資源定義 (manifest.yaml 和 extensions.yaml)，以擴充 GKE 的核心功能。

我們安裝 Agent Sandbox 基礎架構的原因：標準 Kubernetes 叢集不支援分配受保護的隨選沙箱。註冊 Agent Sandbox CRD 會擴充 GKE 的控制層，讓 Kubernetes 使用自訂資源 (例如 SandboxTemplates 和 SandboxClaims)，以原生方式調度管理安全的沙箱微容器。

10. 設定命名空間、服務帳戶和 Workload Identity

這個指令碼會佈建 hackathon-judge 命名空間、註冊 Kubernetes 服務帳戶 (KSA)，並建立 Workload Identity 對應，授予 GKE Pod 目標 Google Cloud 權限。

11. 部署沙箱路由器

指令碼會套用 k8s/sandbox_router.yaml 資訊清單，啟動 Sandbox Router 部署作業和服務，並等待這些項目達到健康狀態。

部署 Sandbox Router 的原因：Sandbox Router 是中央內部控制層閘道。這個服務會公開簡單的 API，供 ADK 評估工作人員代理程式呼叫，以聲明、存取或發布安全沙箱，並管理路由對應，以及從應用程式邏輯中抽象化叢集層級的 Pod 分配。

6. 設定 Agent Sandbox Gateway、Claims 和 WarmPool

在這個步驟中，您將手動設定專用沙箱網路閘道、註冊沙箱聲明範本，並部署沙箱 WarmPool，以啟用超低延遲沙箱。

來源環境變數

套用需要環境變數的範本前，請先取得 setup-env.sh 指令碼，將所有必要變數剖析並匯出至殼層：

source ./setup-env.sh

套用沙箱閘道

部署專為轉送沙箱流量設定的閘道：

kubectl apply -f k8s/sandbox-gateway.yaml

為何要部署 Sandbox Gateway：Sandbox Gateway 是安全的高效能 Ingress 控制器，專門用於沙箱路由。這項功能會隔離沙箱網路，提供安全的本機目標，讓工作人員代理程式與已聲明的沙箱通訊，不必對外公開端點。

套用沙箱聲明範本

使用 envsubst 填入含有有效環境變數的沙箱範本定義，然後套用：

source ./setup-env.sh
envsubst < k8s/sandbox-claim-template.yaml | kubectl apply -f -

我們為何要部署沙箱聲明範本：沙箱聲明範本可做為定義環境的藍圖設定。這項設定會指定要執行的容器映像檔 (預先封裝開發人員工具)、環境參數 (GCP 專案 ID)、連接埠和資源限制 (CPU/記憶體目標)。這項設定會讓 GKE 使用 gVisor (gvisor 執行階段) 執行這些容器執行個體，確保不受信任的參與者程式碼會在額外的核心虛擬化隔離層下執行。

套用 Sandbox WarmPool

將 Sandbox WarmPool 套用至預先初始化的執行中沙箱：

kubectl apply -f k8s/sandbox-warmpool.yaml

確認暖池待命執行個體已順利啟動：

kubectl get pods -n hackathon-judge -l app=sandbox

預熱延遲時間：GKE 最多可能需要一分鐘，才能提取沙箱化容器映像檔並啟動預熱副本。使用監看旗標 -w 執行這個指令，或重複執行這個指令，直到看到所有 5 個副本都處於 Running 狀態，再繼續執行部署步驟。

我們為何要部署 Sandbox WarmPool：視需要佈建、排程、提取映像檔及啟動新的容器 Pod，會造成大量的啟動負擔 (冷啟動時間超過 30 秒)。Sandbox WarmPool 會維護現用預先暖機沙箱 Pod 的待命集區 (預設為 5 個副本)。當工作人員代理程式要求評估環境時，Sandbox 路由器會立即分配預先暖機的執行中 Pod，將啟動延遲時間縮短至不到一秒。

7. 部署應用程式元件

安全沙箱基礎架構完全啟用後，您現在可以部署中央後端 API、工作人員代理程式、React 網頁介面和 Ingress Gateway 對應。

部署後端

部署協調器 REST API 後端：

source ./setup-env.sh
envsubst < k8s/backend.yaml | kubectl apply -f -

部署代理

部署 ADK 評估工作站代理：

source ./setup-env.sh
envsubst < k8s/agent.yaml | kubectl apply -f -

部署前端

部署互動式網頁使用者介面：

source ./setup-env.sh
envsubst < k8s/frontend.yaml | kubectl apply -f -

設定外部閘道和轉送

部署主要閘道和 Ingress HTTP 路由，對應外部用戶端流量：

kubectl apply -f k8s/gateway.yaml

為何要部署外部 Ingress 閘道：外部閘道會使用 Kubernetes Gateway API 公開服務。這會佈建負載平衡的公開 IP 位址，並根據路徑規則對應路徑，將 /api/* 下的 API 要求導向 Go 後端，並將所有其他用戶端網路流量 (/) 對應至 React 前端，確保公開叢集存取安全。

驗證推出作業

封鎖 Shell 執行作業，並等待所有三項核心服務部署作業都達到正常運作狀態，準備好推出：

kubectl rollout status deployment/backend -n hackathon-judge --timeout=300s
kubectl rollout status deployment/agent -n hackathon-judge --timeout=300s
kubectl rollout status deployment/frontend -n hackathon-judge --timeout=300s

8. 驗證及使用應用程式

存取 UI

擷取新佈建的主要負載平衡器閘道外部公開 IP 位址：

等待負載平衡器佈建完成：Google Cloud 的全域外部負載平衡器需要 2 到 5 分鐘，才能分配 IP 資源、設定全域轉送規則，以及設定全域路由路徑。如果 ADDRESS 欄位空白或顯示 ，請稍候幾分鐘再重新查詢。

如要即時查看佈建狀態，請執行指令並加上監看旗標 (-w)，然後等待 ADDRESS 欄位填入公開 IP 位址：

kubectl get gateway -n hackathon-judge hackathon-judge-gateway -w

成功佈建後，您應該會看到類似以下的輸出內容：

NAME                      CLASS    ADDRESS          PROGRAMMED   AGE
hackathon-judge-gateway   gke-l7   34.120.120.120   True         3m

在 ADDRESS 欄中看到有效的公開 IP 位址，且 PROGRAMMED 狀態為 True 時，請按下 Ctrl+C 停止監看。

為何要取得 Gateway 狀態：Gateway API 會處理公開 Ingress。檢查閘道狀態會傳回 Google Cloud 外部全域負載平衡器分配給叢集的公開負載平衡外部 IP 位址，代表平台的公開位址。

在瀏覽器中開啟已分配的公開 IP 位址，載入 Hackathon Judge 資訊主頁。

提交工作

• 使用前端 UI 導覽至資訊主頁，然後選取黑客松。

• 在任何專案上，您都可以點選 Run Agent，開始讓代理程式根據評量表評估整個專案。

觀看沙箱啟動

監控 hackathon-judge 命名空間內的運作中 Pod，查看系統是否動態宣告並佈建沙箱 Pod，以評估執行作業：

kubectl get pods -n hackathon-judge -w

依設計補充 WarmPool：當工作站代理程式從集區要求預先暖機的沙箱 Pod 時，您會在清單中看到新的沙箱 Pod 啟動 (從 Pending -> ContainerCreating -> Running 轉換)。這是設計使然！GKE 代理程式沙箱控制器會主動監控集區大小，並維持預先暖機的有效沙箱容器確切目標數量 (預設為 3 個)。一旦待命容器遭到聲明，控制器會立即排定新的預先暖機 Pod 來取代，確保平台隨時準備好迎接下一個評估工作，啟動時間不到一秒。

檢查工作人員代理程式 Pod 的記錄，逐步瞭解 ADK 評估邏輯：

kubectl logs -l app=agent -n hackathon-judge

檢查代理程式記錄的原因：檢查工作人員代理程式記錄時，評估管道的詳細內部步驟會即時顯示。您可以追蹤 ADK 代理程式擷取工作、要求沙箱容器、執行編譯目標、使用 Gemini 分析報表，以及發布評量表。

9. (選用) 運作方式

Agent Sandbox 架構

雖然 BigQuery AI 函式非常適合評估以文字為主的提交內容和 README 聲明，但要評估工程專案，就必須編譯程式碼、安裝第三方程式庫，以及執行實際的測試套件。

執行原始使用者程式碼會造成巨大的安全風險，包括主機遭入侵、容器中斷，以及未經授權存取資源。GKE Agent Sandbox 架構會使用 gVisor (runsc) 虛擬化，協調處理隔離的沙箱工作負載，藉此降低這些風險。

系統互動流程

下圖顯示在安全沙箱評估執行期間，事件驅動系統的各個元素如何通訊：

參與度工具和元件如何搭配運作

• React 前端 UI：提供互動式介面，使用者可在其中設定條件模型、註冊團隊、提交專案網址，以及查看最終評分表，包括完整檔案差異和工程註解。
• Go REST 後端 API：管理全域 API 端點。這項服務會將專案設定儲存在 BigQuery 中，並將評估工作推送至 Pub/Sub，以解除重度運算執行管道的耦合。
• Google Pub/Sub：以訊息為導向的代理程式，可將工作訊息安全地保留在佇列中，並在 API 和作用中的工作者執行個體之間，以非同步方式協調通訊。
• Python ADK 工作站 (監管代理程式)：從 Pub/Sub 提取工作的背景工作站。這項功能會運用 Google Agent Development Kit (ADK) 啟動高階監督代理，並指示該代理協調評估作業。主管會叫用主要工具 evaluate_repository，委派深層原始指令測試。
• Sandbox 路由器和閘道 (GKE 控制層)：內部控制閘道，用於註冊標準 Sandbox 自訂資源定義 (SandboxClaims、SandboxTemplates)。這個閘道會協調 GKE 網路，以分配及保護 Pod，並將連線串流傳回給工作站用戶端。
• 沙箱 WarmPool：為避免 GKE 容器啟動時間過長 (「冷啟動」超過 30 秒)，WarmPool 會維持待命中的有效 Pod。沙箱一經聲明，路由器就會立即在不到一秒的時間內完成對應，並在發布時排定回收作業。
• gVisor (runsc) 隔離：使用者空間虛擬核心，可做為安全沙箱邊界。這項功能會攔截從容器空間到 GKE 節點核心的系統呼叫，確保危險的原始指令 (例如系統指令碼或套件設定) 在絕對虛擬化隔離環境下執行。
• FastAPI Sandbox Runtime：在沙箱容器中執行的輕量型 Python API 伺服器。這項服務會公開安全端點 (/execute、/upload、/download)，讓外部工作人員工具可操控檔案及觸發 Shell 工作。
• Gemini CLI (@google/gemini-cli)：安裝在沙箱中的自主代理指令碼。使用開發人員環境執行階段旗標 (--yolo) 觸發時，這項功能會使用嚴格的評分說明表 (prompt.md) 和條件定義 (criteria.md)，執行下列操作：
  • 動態分析程式碼基底階層 (使用 tree 或 ripgrep 等工具)。
  • 自動安裝必要條件 (透過 npm install、pip install、go build 等指令)。
  • 執行實際開發測試 (例如 npm test 或 pytest) 來驗證功能。
  • 呼叫 Vertex AI 模型 (透過容器的 Workload Identity 繫結憑證)，評估檔案邏輯、根據 README 交叉檢查聲明、偵測幽靈功能、記錄品質問題，以及編寫結構化評分表報表至 evaluation.json。
• 標準開發人員環境：將節點、npm、yarn、pnpm、python、pip、uv、go、gh、git、tree、ripgrep 和 playwright 綁定至沙箱容器映像檔，為自主子代理程式提供完整的測試工作區。

Workload Identity 安全性運作方式：請注意，在基礎架構設定期間，沙箱 GKE 服務帳戶 (hackathon-judge-sandbox-sa) 已獲得標準 roles/aiplatform.user IAM 權限。當沙箱 Pod 內的 Gemini CLI 向 Vertex AI 要求模型回覆時，GKE 的 Workload Identity 會在幕後自動產生金鑰並檢查憑證！容器絕不會儲存靜態 API 金鑰或硬式編碼的雲端憑證，可自動維持頂級安全防護措施。

10. 清除

如要避免系統持續向您的 Google Cloud 帳戶收取費用，請刪除在本程式碼研究室中建立的資源。

./destroy.sh

我們為何要清理資源：Google Cloud 採用資源用量計費模式。即使處於閒置狀態，GKE Autopilot 叢集、網路負載平衡器和永久磁碟等有效資源仍會持續產生費用。執行這個步驟會刪除叢集命名空間來清除 Kubernetes 物件，並刪除 GKE Autopilot 叢集主機本身，立即終止所有基礎計費費用。

11. 恭喜

恭喜！您已成功在 GKE 上部署 Hackathon Judge 應用程式，並使用 Agent Sandbox！

您已實作安全現代化的事件驅動式 AI 平台，能夠在隔離的容器化安全限制下，測試及評估不受信任的程式碼庫提交內容。

目前所學內容

• GKE 基礎架構：如何佈建 GKE Autopilot 和支援的 Google Cloud 服務，例如 Pub/Sub 和 BigQuery。
• 代理程式沙箱設定：如何設定自訂資源定義、SandboxTemplate、SandboxClaim 和高效能 Sandbox WarmPool。
• 微服務部署：如何設定 Workload Identity 繫結，以及部署多元件微服務架構 (Frontend React、REST Go、Worker ADK Agent 和 Isolated Sandbox)。
• 安全沙箱：如何利用 gVisor 虛擬化容器，在 GKE 節點上安全地執行不受信任的第三方指令。

後續步驟

• 查看 Agent Sandbox 說明文件。
• 進一步瞭解 GKE Autopilot 功能。
• 查看 Agent Platform 說明文件。

參考文件

• Kubernetes Gateway API 規格
• gVisor 沙箱執行階段