将 Filestore 代理卷与 GKE Agent Substrate 搭配使用

注意： 所有 Google Cloud客户都可以使用 Filestore 代理卷功能进行评估和非生产用途。如需为您的Google Cloud 项目申请访问权限，请提交 Filestore 代理卷访问权限申请表单。在有限的正式版计划下，我们根据许可名单提供生产环境支持。如需查看您是否符合条件或申请制作支持，请使用访问权限申请表单。

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 历史记录和 build 缓存仍会保留在卷中。
3. 即时恢复：当开发者发送新提示时，代理平台会在 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 驱动程序

如需将 Filestore 代理卷与 Agent Substrate 搭配使用，您必须在运行交互式 Agent Substrate 安装程序时选择可选的 Filestore CSI 驱动程序步骤。

Agent Substrate 控制平面 (ateapi) 通过网络 gRPC 直接与 Filestore CSI 驱动程序控制器通信。CSI 驱动程序会根据每个 actor 的生命周期，从 Filestore 卷池中动态预配、连接和分离每个 actor 的卷。

注意： 如果您未使用 Agent Substrate 安装程序安装 CSI 驱动程序，则可以使用《GKE 基底集成叠加层指南》中的自动部署脚本 (deploy.sh) 或 Kustomize 清单手动安装。

创建使用 Filestore 卷的工作负载

在 Agent Substrate 中，您可以在 ActorTemplate 资源中以声明方式定义外部 Filestore 卷，而不是创建单独的 Kubernetes PersistentVolumeClaim 对象。以下步骤将引导您完成以下操作：配置 Filestore StorageClass 和 CSIDriverConfig、部署装载外部 Filestore 卷的 WorkerPool 和 ActorTemplate，以及管理 actor 生命周期。

创建 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

注意： 如果您使用 deploy.sh 部署 CSI 驱动程序，并带有 --volumepool-location 和 --volumepool-name 标志，系统会自动创建 StorageClass。

注册 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

注意： 如果您使用 Agent Substrate 安装程序或 deploy.sh 安装了 CSI 驱动程序，则系统会自动注册此 CSIDriverConfig 资源。

定义 WorkerPool 和 ActorTemplate

1. 创建 ate-demo atespace 和 Kubernetes 命名空间，以作为工作器池、Actor 模板和 Actor 的隔离边界：

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

2. 创建 WorkerPool 资源，以保持物理备用工作负载处于可托管 actor 沙盒的状态。将以下清单保存为 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 存储桶。

   在此清单中，volumes[].externalVolumeTemplate 指定了所请求的卷容量 (5Gi) 和 StorageClass (substrate-volumepool-sc)，后者的 provisioner 与您的 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 并准备好其黄金快照后，您可以创建 actor 实例并管理其执行状态：

1. 从 stateful-agent-template 创建新 actor：

   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. 在 actor 处于闲置状态时将其暂停：

   kubectl ate suspend actor ACTOR_NAME \
       -a ate-demo
   

   暂停执行器会将其内存状态检查点保存到 Cloud Storage，卸载并分离 Filestore 卷，同时保留卷上的所有工作区文件，并释放工作负载。

3. 当有新请求或任务到达时，恢复 actor：

   kubectl ate resume actor ACTOR_NAME \
       -a ate-demo
   

   恢复 actor 会将其分配给可用的工作负载，恢复其内存快照，并重新附加位于 /mnt/shared 的现有 Filestore 卷，所有文件都完好无损。

后续步骤

• 为 GKE 设置环境。
• 使用 Agent Sandbox 配置预热沙盒。
• 通过 Agent Sandbox 延迟绑定探索动态存储。