将 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 驱动程序

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

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

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

注册 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 命名空间，作为工作器池、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)，其预配工具与您的 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

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

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

    kubectl ate resume actor ACTOR_NAME \
    -a ate-demo

    恢复 actor 会将其分配给可用的工作负载，恢复其内存快照，并在 /mnt/shared 重新挂接现有 Filestore 卷，同时保持所有文件完好无损。

后续步骤