將 Filestore 代理程式磁碟區與 GKE Agent Substrate 搭配使用

Google Kubernetes Engine (GKE) Agent Substrate 是一種基礎架構平台，可管理具狀態 AI 代理程式沙箱的生命週期。Agent Substrate 可讓平台暫停閒置的代理工作負載，節省運算費用，並在收到新提示或工作時，於不到一秒內恢復工作負載。

Filestore 代理程式磁碟區可為 Agent Substrate 提供永久儲存空間層，在沙箱暫停和恢復週期之間保留工作區檔案、程式碼存放區和暫存區構件。

Agent Substrate 如何使用代理數量

以下步驟說明 Agent Substrate 和 Filestore 代理程式磁碟區如何支援互動式程式碼編寫代理程式，協助開發人員建構功能、執行測試及偵錯程式碼：

  1. 工作階段初始化：開發人員提交工作時，Agent Substrate 會在 GKE 上建立沙箱環境，並掛接專屬的 Filestore 磁碟區。代理會複製專案存放區、安裝依附元件，並準備工作區。
  2. 節省成本的閒置暫停：開發人員在檢視程式碼差異或製作下一個提示時，Agent Substrate 會卸載磁碟區並終止運算環境。運算資源使用率會降至零，但所有工作區檔案、Git 記錄和建構快取都會保留在磁碟區中。
  3. 立即恢復：開發人員傳送新提示時，Agent Substrate 會聲明預先暖機的沙箱，並在 100 毫秒內重新附加現有磁碟區。代理程式會立即恢復工作負載，且檔案系統內容完整無缺，避免耗時的存放區重新複製或依附元件重新安裝。

詳情請參閱 Agent Substrate 說明文件。

如要在 GKE Agent Substrate 上執行有狀態的代理程式工作負載，並使用 Filestore 代理程式磁碟區，請安裝 Agent Substrate、設定 Filestore CSI 驅動程式整合，並定義代理程式工作負載，以使用動態 CSI 磁碟區。

安裝 Agent Substrate

如要準備 Google Cloud 專案並在 GKE Standard 叢集上安裝 Agent Substrate，請按照「在 GKE 上安裝 Agent Substrate」一文中的操作說明進行。

安裝及設定 Filestore CSI 驅動程式

如要搭配 Agent Substrate 使用 Filestore 代理程式磁碟區，請在執行互動式 Agent Substrate 安裝程式時，選取選用的「Filestore CSI driver」(Filestore CSI 驅動程式)步驟。

Agent Substrate 控制層 (ateapi) 會透過網路 gRPC 直接與 Filestore CSI 驅動程式控制器通訊。CSI 驅動程式會根據每個參與者的生命週期，從 Filestore 磁碟區集區動態佈建、連結及取消連結每個參與者的磁碟區。

建立使用 Filestore 磁碟區的工作負載

在 Agent Substrate 中，您可以在 ActorTemplate 資源中以宣告方式定義外部 Filestore 磁碟區，不必建立個別的 Kubernetes PersistentVolumeClaim 物件。下列步驟會逐步說明如何設定 Filestore StorageClass 和 CSIDriverConfig、部署 WorkerPool 和 ActorTemplate (掛接外部 Filestore 磁碟區)，以及管理參與者生命週期。

建立 StorageClass

建立名為 storageclass.yaml 的檔案，從 Filestore 磁碟區集區佈建動態磁碟區：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: substrate-volumepool-sc
provisioner: filestore.csi.storage.gke.io
parameters:
  volume-pool: "projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_NAME"
allowVolumeExpansion: false
reclaimPolicy: Delete
volumeBindingMode: Immediate

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • LOCATION：磁碟區集區所在的區域，例如 us-central1。
  • VOLUME_POOL_NAME：Filestore 磁碟區集區的名稱。

套用 StorageClass：

kubectl apply -f storageclass.yaml

註冊 CSIDriverConfig

CSIDriverConfig 資源會將 Kubernetes StorageClass 佈建工具 (filestore.csi.storage.gke.io) 橋接至 Filestore CSI 控制器服務的網路 gRPC 端點，以及 CSI 節點外掛程式的本機 Unix 網域通訊端路徑。

建立名為 csi-driver-config.yaml 的檔案：

apiVersion: ate.dev/v1alpha1
kind: CSIDriverConfig
metadata:
  name: filestore.csi.storage.gke.io
spec:
  driverName: filestore.csi.storage.gke.io
  controllerEndpoint: tcp://csi-filestore-controller.gcp-filestore-csi-driver.svc:10000
  nodeSocketOverride: unix:///var/lib/kubelet/plugins/filestore.csi.storage.gke.io/csi.sock
  tls:
    enabled: true
    usePodIdentity: true
    serverName: csi-filestore-controller.gcp-filestore-csi-driver.svc

套用 CSIDriverConfig：

kubectl apply -f csi-driver-config.yaml

定義 WorkerPool 和 ActorTemplate

  1. 建立 ate-demo atespace 和 Kubernetes 命名空間，做為工作站集區、執行器範本和執行器的隔離界線：

    kubectl ate create atespace ate-demo
kubectl create namespace ate-demo

  2. 建立 WorkerPool 資源，維持實體待命工作負載，隨時可代管參與者沙箱。將下列資訊清單儲存為 worker-pool.yaml：

    apiVersion: ate.dev/v1alpha1
kind: WorkerPool
metadata:
  name: agent-pool
  namespace: ate-demo
  labels:
    workload: stateful-agent
spec:
  replicas: 5
  workerImage: ko://github.com/agent-substrate/substrate/cmd/ateom-gvisor

  3. 套用 WorkerPool 資訊清單：

    kubectl apply -f worker-pool.yaml

  4. 建立名為 actor-template.yaml 的檔案，定義可從 substrate-volumepool-sc 掛接 5 GiB 磁碟區的 ActorTemplate：

    metadata:
  atespace: ate-demo
  name: stateful-agent-template
workerSelector:
  matchLabels:
    workload: stateful-agent
containers:
- name: agent
  image: CONTAINER_IMAGE
  volumeMounts:
  - name: shared-storage
    mountPath: /mnt/shared
  readyz:
    httpGet:
      path: /readyz
      port: 8080
sandboxConfig:
  sandboxClass: SANDBOX_CLASS_GVISOR
  configName: gvisor-default
snapshotsConfig:
  storageLocation: gs://SNAPSHOT_BUCKET/stateful-agent
volumes:
- name: shared-storage
  externalVolumeTemplate:
    capacity: 5Gi
    storageClassName: substrate-volumepool-sc

    更改下列內容：

    • CONTAINER_IMAGE：代理程式工作負載的容器映像檔，例如 gcr.io/my-project/agent-app@sha256:7f28ab0...。
    • SNAPSHOT_BUCKET：Agent Substrate 用於儲存參與者快照的 Cloud Storage bucket。

    在這個資訊清單中，volumes[].externalVolumeTemplate 會指定要求的磁碟區容量 (5Gi) 和 StorageClass (substrate-volumepool-sc)，其佈建工具與 CSIDriverConfig 相符，而 containers[].volumeMounts 會在 /mnt/shared 掛接該磁碟區。volumes 中宣告的每個磁碟區，都必須由至少一個容器掛接。

  5. 使用 kubectl ate CLI，透過 Agent Substrate API 建立 ActorTemplate：

    kubectl ate create actor-template -f actor-template.yaml

建立、暫停及繼續執行者

建立 ActorTemplate 並準備好黃金快照後，即可建立參與者執行個體並管理其執行狀態：

  1. 從 stateful-agent-template 建立新參與者：

    kubectl ate create actor ACTOR_NAME \
    --template=stateful-agent-template \
    -a ate-demo

    將 ACTOR_NAME 替換為您執行者的 DNS-1123 標籤名稱，例如 my-agent-1。

    建立 Actor 時，Agent Substrate 會從 substrate-volumepool-sc 動態佈建專屬的 Filestore 磁碟區，並掛接至 /mnt/shared。

  2. 在執行者閒置時暫停：

    kubectl ate suspend actor ACTOR_NAME \
    -a ate-demo

    暫停執行者會將記憶體狀態檢查點儲存至 Cloud Storage、卸載並分離 Filestore 磁碟區，同時保留磁碟區上的所有工作區檔案，並釋出工作負載。

  3. 有新要求或工作抵達時，繼續執行參與者：

    kubectl ate resume actor ACTOR_NAME \
    -a ate-demo

    繼續執行參與者會將其指派給可用的工作負載、還原其記憶體快照，並在 /mnt/shared 重新附加現有的 Filestore 磁碟區，所有檔案都會完好無損。

後續步驟