GKE Agent Substrate で Filestore エージェント ボリュームを使用する

Google Kubernetes Engine（GKE）Agent Substrate は、ステートフル AI エージェント サンドボックスのライフサイクルを管理するインフラストラクチャ プラットフォームです。Agent Substrate を使用すると、プラットフォームはアイドル状態のエージェント ワークロードを一時停止してコンピューティング費用を節約し、新しいプロンプトやタスクが到着したときに 1 秒以内に再開できます。

Filestore エージェント ボリュームは、Agent Substrate の永続ストレージ レイヤを提供し、サンドボックスの停止と再開のサイクル全体でワークスペース ファイル、コード リポジトリ、スクラッチパッド アーティファクトを保持します。

Agent Substrate でエージェントのボリュームがどのように使用されるか

次の手順では、Agent Substrate と Filestore エージェント ボリュームが、開発者が機能の構築、テストの実行、コードのデバッグに役立つインタラクティブ コーディング エージェントをサポートする方法について説明します。

  1. セッションの初期化: デベロッパーがタスクを送信すると、Agent Substrate は GKE にサンドボックス環境を作成し、専用の Filestore ボリュームをマウントします。エージェントはプロジェクト リポジトリのクローンを作成し、依存関係をインストールして、ワークスペースを準備します。
  2. 費用対効果の高いアイドル状態のサスペンション: デベロッパーがコードの差分を確認したり、次のプロンプトを作成したりしている間、Agent Substrate はボリュームをアンマウントし、コンピューティング環境を終了します。コンピューティング リソースの使用率はゼロに低下しますが、すべてのワークスペース ファイル、Git 履歴、ビルド キャッシュはボリュームに保持されます。
  3. 即時再開: デベロッパーが新しいプロンプトを送信すると、Agent Substrate は事前ウォーミングされたサンドボックスを要求し、既存のボリュームを 100 ミリ秒以内に再接続します。エージェントは、ファイル システムのコンテキストを完全に維持したままワークロードを直ちに再開し、時間のかかるリポジトリの再クローンや依存関係の再インストールを回避します。

詳細については、Agent Substrate のドキュメントをご覧ください。

Filestore エージェント ボリュームを使用して GKE Agent Substrate でステートフル エージェント ワークロードを実行するには、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 ドライバの手順を選択する必要があります。

Agent Substrate コントロール プレーン（ateapi）は、ネットワーク gRPC 経由で Filestore CSI ドライバ コントローラと直接通信します。CSI ドライバは、各アクターのライフサイクルと同期して、アクターごとのボリュームを Filestore ボリューム プールから動的にプロビジョニング、アタッチ、デタッチします。

Filestore ボリュームを使用するワークロードを作成する

Agent Substrate では、個別の Kubernetes PersistentVolumeClaim オブジェクトを作成するのではなく、ActorTemplate リソースで外部 Filestore ボリュームを宣言的に定義します。次の手順では、Filestore StorageClass と CSIDriverConfig の構成、外部 Filestore ボリュームをマウントする WorkerPool と ActorTemplate のデプロイ、アクターのライフサイクルの管理について説明します。

StorageClass を作成する

Filestore ボリューム プールから動的ボリュームをプロビジョニングする storageclass.yaml という名前のファイルを作成します。

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 Namespace を作成します。

    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. substrate-volumepool-sc から 5 GiB のボリュームをマウントする ActorTemplate を定義する actor-template.yaml という名前のファイルを作成します。

    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 バケット。

    このマニフェストでは、volumes[].externalVolumeTemplate はリクエストされたボリューム容量（5Gi）と、プロビジョナーが CSIDriverConfig と一致する StorageClass（substrate-volumepool-sc）を指定します。一方、containers[].volumeMounts はそのボリュームを /mnt/shared にマウントします。volumes で宣言されたすべてのボリュームは、少なくとも 1 つのコンテナによってマウントされる必要があります。

  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 など）に置き換えます。

    アクターを作成すると、エージェント サブストレートは 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

    アクターを再開すると、利用可能なワークロードに割り当てられ、メモリ スナップショットが復元され、既存の Filestore ボリュームが /mnt/shared に再アタッチされ、すべてのファイルがそのまま残ります。

次のステップ