將 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」步驟。

Agent Substrate 控制層 (ateapi) 會透過網路 gRPC，直接與 Filestore CSI 驅動程式控制器通訊。CSI 驅動程式會根據每個 actor 的生命週期，動態佈建、附加及卸載 Filestore 磁碟區集區中的個別 actor 磁碟區。

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

在 Agent Substrate 中，您可以在 ActorTemplate 資源中以宣告方式定義外部 Filestore 磁碟區，而不必建立個別的 Kubernetes PersistentVolumeClaim 物件。下列步驟將引導您設定 Filestore StorageClass 和 CSIDriverConfig、部署掛接外部 Filestore 磁碟區的 WorkerPool 和 ActorTemplate，以及管理執行者生命週期。

建立 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 命名空間，做為 worker 集區、actor 範本和 actor 的隔離邊界：

    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 用來儲存 actor 快照的 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

建立、暫停及恢復 actor

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

  1. 從 stateful-agent-template 建立新的執行者：

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

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

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

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

    kubectl ate suspend actor ACTOR_NAME \
    -a ate-demo

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

  3. 當有新的要求或任務時，恢復執行 actor：

    kubectl ate resume actor ACTOR_NAME \
    -a ate-demo

    恢復執行 actor 時，系統會將其指派給可用的工作負載、還原記憶體快照，並在 /mnt/shared 重新附加現有的 Filestore 磁碟區，所有檔案都會保持完整。

後續步驟