Usar volumes do agente do Filestore com o Agent Substrate do GKE

Observação:o recurso de volumes do agente do Filestore está disponível para todos os clientes do Google Cloudpara avaliação e uso não produtivo. Para solicitar acesso ao seu projetoGoogle Cloud , envie o formulário de solicitação de acesso aos volumes do agente do Filestore. O suporte Production é oferecido com base em uma lista de permissões em um programa de disponibilidade geral (GA) limitado. Para verificar sua qualificação ou pedir suporte de produção, use o formulário de acesso.

O Agent Substrate do Google Kubernetes Engine (GKE) é uma plataforma de infraestrutura que gerencia o ciclo de vida de sandboxes de agentes de IA com estado. O Agent Substrate permite que plataformas suspendam cargas de trabalho de agentes inativos para economizar custos de computação e as retomem em menos de um segundo quando novos comandos ou tarefas chegam.

Os volumes do agente do Filestore fornecem a camada de armazenamento permanente para o Agent Substrate, preservando arquivos do espaço de trabalho, repositórios de código e artefatos do bloco de notas em ciclos de suspensão e retomada da sandbox.

Como o Agent Substrate usa volumes de agentes

As etapas a seguir descrevem como o Agent Substrate e os volumes de agentes do Filestore oferecem suporte a um agente de programação interativo que ajuda os desenvolvedores a criar recursos, executar testes e depurar código:

1. Inicialização da sessão:quando um desenvolvedor envia uma tarefa, o Agent Substrate cria um ambiente de sandbox no GKE e monta um volume dedicado do Filestore. O agente clona o repositório do projeto, instala as dependências e prepara o espaço de trabalho.
2. Suspensão ociosa econômica:enquanto o desenvolvedor revisa as diferenças de código ou cria o próximo comando, o Agent Substrate desmonta o volume e encerra o ambiente de computação. A utilização de recursos de computação cai para zero, enquanto todos os arquivos do espaço de trabalho, o histórico do Git e os caches de build permanecem persistentes no volume.
3. Retomada instantânea:quando o desenvolvedor envia um novo comando, o Agent Substrate reivindica um sandbox pré-aquecido e reconecta o volume atual em menos de 100 ms. O agente retoma imediatamente a carga de trabalho com o contexto completo do sistema de arquivos intacto, evitando novas clonagens demoradas de repositório ou reinstalações de dependências.

Para mais informações, consulte a documentação do Agent Substrate.

Para executar cargas de trabalho de agente com estado no GKE Agent Substrate com volumes de agente do Filestore, instale o Agent Substrate, configure a integração do driver CSI do Filestore e defina as cargas de trabalho do agente para usar volumes CSI dinâmicos.

Instalar o Agent Substrate

Para preparar seu projeto Google Cloud e instalar o Agent Substrate em um cluster GKE Standard, siga as instruções em Instalar o Agent Substrate no GKE.

Instalar e configurar o driver CSI do Filestore

Para usar volumes de agente do Filestore com o Agent Substrate, selecione a etapa opcional Driver CSI do Filestore ao executar o instalador interativo do Agent Substrate.

O plano de controle do Agent Substrate (ateapi) se comunica diretamente com o controlador do driver CSI do Filestore por gRPC de rede. O driver CSI provisiona, anexa e desanexa dinamicamente volumes por ator do seu pool de volumes do Filestore em sincronia com o ciclo de vida de cada ator.

Observação: se você não instalou o driver CSI com o instalador do Agent Substrate, é possível fazer isso manualmente usando o script de implantação automatizada (deploy.sh) ou os manifestos do Kustomize no guia de sobreposição de integração do GKE Substrate.

Criar cargas de trabalho que usam volumes do Filestore

No Agent Substrate, você define volumes externos do Filestore de maneira declarativa em um recurso ActorTemplate em vez de criar objetos PersistentVolumeClaim separados do Kubernetes. As etapas a seguir mostram como configurar um StorageClass e um CSIDriverConfig do Filestore, implantar um WorkerPool e um ActorTemplate que ativam um volume externo do Filestore e gerenciar o ciclo de vida do ator.

Criar o StorageClass

Crie um arquivo chamado storageclass.yaml para provisionar volumes dinâmicos do seu pool de volumes do 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

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• LOCATION: a região em que o pool de volumes está localizado, como us-central1.
• VOLUME_POOL_NAME: o nome do pool de volumes do Filestore.

Aplique o StorageClass:

kubectl apply -f storageclass.yaml

Observação: se você implantou o driver CSI usando deploy.sh com as flags --volumepool-location e --volumepool-name, o StorageClass será criado automaticamente.

Registre o CSIDriverConfig

O recurso CSIDriverConfig conecta o provisionador StorageClass do Kubernetes (filestore.csi.storage.gke.io) ao endpoint gRPC de rede do serviço de controlador CSI do Filestore e ao caminho de soquete de domínio Unix local do plug-in de nó CSI.

Crie um arquivo chamado 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

Aplique o CSIDriverConfig:

kubectl apply -f csi-driver-config.yaml

Observação: se você instalou o driver CSI usando o instalador do Agent Substrate ou deploy.sh, esse recurso CSIDriverConfig será registrado automaticamente.

Defina WorkerPool e ActorTemplate

1. Crie o namespace ate-demo do atespace e do Kubernetes para servir como o limite de isolamento do pool de trabalhadores, do modelo de ator e dos atores:

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

2. Crie um recurso WorkerPool para manter as cargas de trabalho de espera física prontas para hospedar sandboxes de atores. Salve o seguinte manifesto como 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. Aplique o manifesto WorkerPool:

   kubectl apply -f worker-pool.yaml
   

4. Crie um arquivo chamado actor-template.yaml definindo o ActorTemplate que monta um volume de 5 GiB de 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
   

   Substitua:

   • CONTAINER_IMAGE: a imagem do contêiner para sua carga de trabalho do agente, como gcr.io/my-project/agent-app@sha256:7f28ab0....
   • SNAPSHOT_BUCKET: o bucket do Cloud Storage usado pelo Agent Substrate para armazenar snapshots de atores.

   Neste manifesto, volumes[].externalVolumeTemplate especifica a capacidade de volume solicitada (5Gi) e a StorageClass (substrate-volumepool-sc) cujo provisionador corresponde ao seu CSIDriverConfig, enquanto containers[].volumeMounts monta esse volume em /mnt/shared. Todos os volumes declarados em volumes precisam ser ativados por pelo menos um contêiner.

5. Crie o ActorTemplate usando a API Agent Substrate com a CLI kubectl ate:

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

Criar, suspender e retomar um ator

Depois que o ActorTemplate for criado e o snapshot de referência estiver pronto, você poderá criar uma instância de ator e gerenciar o estado de execução dela:

1. Crie um novo ator de stateful-agent-template:

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

   Substitua ACTOR_NAME por um nome de rótulo DNS-1123 para seu ator, como my-agent-1.

   Quando você cria o ator, o Agent Substrate provisiona dinamicamente um volume dedicado do Filestore de substrate-volumepool-sc e o monta em /mnt/shared.

2. Suspender o ator quando ele ficar inativo:

   kubectl ate suspend actor ACTOR_NAME \
       -a ate-demo
   

   A suspensão do ator faz um checkpoint do estado da memória no Cloud Storage, desmonta e desconecta o volume do Filestore, preservando todos os arquivos do espaço de trabalho no volume e libera a carga de trabalho.

3. Retomar o ator quando uma nova solicitação ou tarefa chegar:

   kubectl ate resume actor ACTOR_NAME \
       -a ate-demo
   

   Ao retomar o ator, ele é atribuído a uma carga de trabalho disponível, o snapshot de memória é restaurado e o volume do Filestore é reconectado em /mnt/shared com todos os arquivos intactos.

A seguir

• Configure o ambiente para o GKE.
• Configure sandboxes pré-aquecidos com o sandbox do agente.
• Conheça o armazenamento dinâmico com a vinculação tardia do sandbox do agente.