Utilizzare i volumi dell'agente Filestore con GKE Agent Substrate

Google Kubernetes Engine (GKE) Agent Substrate è una piattaforma di infrastruttura che gestisce il ciclo di vita delle Agent Sandbox degli agenti AI stateful. Agent Substrate consente alle piattaforme di sospendere i workload degli agenti inattivi per risparmiare sui costi di computing e riprenderli in meno di un secondo quando arrivano nuovi prompt o attività.

I volumi per agenti Filestore forniscono il livello di archiviazione permanente per Agent Substrate, preservando i file dell'area di lavoro, i repository di codice e gli artefatti dello scratchpad durante i cicli di sospensione e ripresa della sandbox.

In che modo Agent Substrate utilizza i volumi per agenti

I passaggi seguenti descrivono in che modo Agent Substrate e i volumi per agenti di Filestore supportano un agente di programmazione interattivo che aiuta gli sviluppatori a creare funzionalità, eseguire test ed eseguire il debug del codice:

  1. Inizializzazione della sessione: quando uno sviluppatore invia un'attività, Agent Substrate crea un ambiente sandbox su GKE e monta un volume Filestore dedicato. L'agente clona il repository del progetto, installa le dipendenze e prepara l'area di lavoro.
  2. Sospensione inattiva conveniente: mentre lo sviluppatore esamina le differenze di codice o crea il prompt successivo, Agent Substrate smonta il volume e termina l'ambiente di computing. L'utilizzo delle risorse di computing scende a zero, mentre tutti i file dell'area di lavoro, la cronologia Git e le cache di build rimangono persistenti nel volume.
  3. Ripristino istantaneo: quando lo sviluppatore invia un nuovo prompt, Agent Substrate richiede una sandbox pre-riscaldata e ricollega il volume esistente in meno di 100 ms. L'agente riprende immediatamente il workload con il contesto del file system completo intatto, evitando di dover ripetere la clonazione del repository o la reinstallazione delle dipendenze.

Per saperne di più, consulta la documentazione di Agent Substrate.

Per eseguire workload degli agenti stateful su GKE Agent Substrate con i volumi per agenti Filestore, installa Agent Substrate, configura l'integrazione del driver CSI Filestore e definisci i workload degli agenti in modo che utilizzino volumi CSI dinamici.

Installa Agent Substrate

Per preparare il progetto Google Cloud e installare Agent Substrate su un cluster GKE Standard, segui le istruzioni riportate in Installa Agent Substrate su GKE.

Installa e configura il driver CSI di Filestore

Per utilizzare i volumi per agenti Filestore con Agent Substrate, devi selezionare il passaggio facoltativo Driver CSI Filestore durante l'esecuzione del programma di installazione interattivo di Agent Substrate.

Il control plane di Agent Substrate (ateapi) comunica direttamente con il controller del driver CSI Filestore tramite gRPC di rete. Il driver CSI esegue il provisioning, il collegamento e lo scollegamento dinamico dei volumi per attore dal pool di volumi Filestore in sincronia con il ciclo di vita di ogni attore.

Crea workload che utilizzano volumi Filestore

In Agent Substrate, i volumi Filestore esterni vengono definiti in modo dichiarativo in una risorsa ActorTemplate anziché creare oggetti Kubernetes PersistentVolumeClaim separati. I passaggi seguenti illustrano come configurare un StorageClass e un CSIDriverConfig Filestore, eseguire il deployment di un WorkerPool e un ActorTemplate che montano un volume Filestore esterno e gestire il ciclo di vita dell'attore.

Crea il StorageClass

Crea un file denominato storageclass.yaml per eseguire il provisioning dei volumi dinamici dal tuo pool di volumi 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

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la regione in cui si trova il pool di volumi, ad esempio us-central1.
  • VOLUME_POOL_NAME: il nome del tuo pool di volumi Filestore.

Applica StorageClass:

kubectl apply -f storageclass.yaml

Registra il CSIDriverConfig

La risorsa CSIDriverConfig collega il provisioner StorageClass di Kubernetes (filestore.csi.storage.gke.io) all'endpoint gRPC di rete del servizio controller CSI di Filestore e al percorso del socket di dominio Unix locale del plug-in del nodo CSI.

Crea un file denominato 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

Applica CSIDriverConfig:

kubectl apply -f csi-driver-config.yaml

Definisci WorkerPool e ActorTemplate

  1. Crea lo spazio dei nomi ate-demo e lo spazio dei nomi Kubernetes che fungeranno da confine di isolamento per il pool di worker, il template degli attori e gli attori:

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

  2. Crea una risorsa WorkerPool per mantenere i workload di standby fisico pronti a ospitare le sandbox degli attori. Salva il seguente manifest come 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. Applica il manifest WorkerPool:

    kubectl apply -f worker-pool.yaml

  4. Crea un file denominato actor-template.yaml che definisce il ActorTemplate che monta un volume da 5 GiB da substrate-volumepool-sc:

    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

    Sostituisci quanto segue:

    • CONTAINER_IMAGE: l'immagine container per il workload dell'agente, ad esempio gcr.io/my-project/agent-app@sha256:7f28ab0....
    • SNAPSHOT_BUCKET: il bucket Cloud Storage utilizzato da Agent Substrate per archiviare gli snapshot degli attori.

    In questo manifest, volumes[].externalVolumeTemplate specifica la capacità del volume richiesta (5Gi) e la StorageClass (substrate-volumepool-sc) il cui provisioner corrisponde alla tua CSIDriverConfig, mentre containers[].volumeMounts monta il volume in /mnt/shared. Ogni volume dichiarato in volumes deve essere montato da almeno un container.

  5. Crea ActorTemplate tramite l'API Agent Substrate utilizzando l'interfaccia a riga di comando kubectl ate:

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

Crea, sospendi e riprendi un attore

Una volta creato ActorTemplate e preparato lo snapshot dorato, puoi creare un'istanza di attore e gestire il relativo stato di esecuzione:

  1. Crea un nuovo attore da stateful-agent-template:

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

    Sostituisci ACTOR_NAME con un nome di etichetta DNS-1123 per il tuo attore, ad esempio my-agent-1.

    Quando crei l'attore, Agent Substrate esegue il provisioning dinamico di un volume Filestore dedicato da substrate-volumepool-sc e lo monta in /mnt/shared.

  2. Sospendi l'attore quando diventa inattivo:

    kubectl ate suspend actor ACTOR_NAME \
    -a ate-demo

    La sospensione dell'attore esegue il checkpoint dello stato della memoria in Cloud Storage, smonta e scollega il volume Filestore preservando tutti i file dell'area di lavoro sul volume e rilascia il workload.

  3. Riprendi l'attore quando arriva una nuova richiesta o un nuovo task:

    kubectl ate resume actor ACTOR_NAME \
    -a ate-demo

    Il ripristino dell'attore lo assegna a un workload disponibile, ripristina lo snapshot della memoria e ricollega il volume Filestore esistente in /mnt/shared con tutti i file intatti.

Passaggi successivi