Este documento fornece implementações de referência para gerenciar o armazenamento do Agent Sandbox no GKE, adaptadas às necessidades do ciclo de vida dos dados dos seus agentes.
Dependendo das necessidades do ciclo de vida dos dados dos seus agentes, escolha uma das seguintes configurações:
- Configurar um espaço de trabalho com estado
- Configurar uma restauração pontual e uma transferência de propriedade
- Configurar um espaço de trabalho temporário
Para mais informações sobre como escolher uma solução de armazenamento, consulte Escolher o armazenamento para cargas de trabalho de agentes de IA.
O documento a seguir usa o StorageClass dynamic-rwo para seleção automática de tipo de disco para provisionar discos compatíveis com tipos de máquina de nós em que os pods do Agent Sandbox no GKE estão programados. Para garantir
que o GKE provisione volumes do Hyperdisk Balanced para
o armazenamento dos seus agentes, programe o Agent Sandbox em
pods do GKE nos nós de famílias de máquinas
compatíveis, como
N4. Caso contrário, o GKE vai usar pd-balanced.
Este documento implementa o modo de acesso a dados do espaço de trabalho isolado particular usando o acesso ReadWriteOnce (RWO). Nesse modo, um agente é iniciado com um
diretório de armazenamento isolado particular ao qual ele tem acesso exclusivo de leitura e gravação.
Salvo indicação em contrário, as implementações de referência neste documento usam a criação direta de sandbox, que é aplicável a agentes que toleram latência de inicialização de vários segundos. Para alcançar latência de inicialização de menos de um segundo para espaços de trabalho de restauração com estado ou pontual, use o Agent Sandbox em pools de aquecimento do GKE. A vinculação do armazenamento a um pod de pool de espera reivindicado requer scripts personalizados e um DaemonSet privilegiado. Para uma implementação de referência, consulte este exemplo do GitHub.
Modos de acesso alternativos
Para oferecer suporte a modos de acesso alternativos, modifique as definições de volume e snapshot nas configurações:
- Espaço de trabalho colaborativo: mude o
accessModesparaReadWriteManye use um StorageClass compatível com RWX, como o Filestore Multishares (Enterprise) (enterprise-multishare-rwx). - Espaço de trabalho de ramificação de análise: monte a pasta de modelos como somente leitura
e forneça um rascunho gravável separado. Para o modelo de base, use um armazenamento que aceite vários anexos somente leitura, como o Hyperdisk ML com o modo de acesso
ReadOnlyMany(ROX) ou o Filestore Multishares com o modo de acesso RWX.
Antes de começar
Verifique se você tem um cluster do GKE com o controlador do Agent Sandbox instalado. Caso contrário, conclua apenas as seguintes seções de Instalar o Agent Sandbox no GKE e retorne a este documento:
- Definir as variáveis de ambiente
- Crie um cluster do GKE
- Instalar o Agent Sandbox
- Aplicar a política de segurança recomendada
Se você concluiu a seção Implantar um ambiente de sandbox desse documento, exclua os recursos de amostra criados para que os nós tenham capacidade suficiente para os sandboxes neste documento:
kubectl delete sandboxclaim sandbox-claim --ignore-not-found
kubectl delete sandboxwarmpool python-runtime-warmpool --ignore-not-found
kubectl delete sandbox sandbox-example-2 --ignore-not-found
Configurar um espaço de trabalho com estado
Use esse padrão para preservar o estado mais recente dos arquivos de um agente. Isso é útil quando o agente precisa preservar o estado quando a sessão do agente é pausada ou encerrada (o Agent Sandbox é excluído) e restaurar os dados do estado mais recente quando a sessão do agente é ativada (o Agent Sandbox é recriado).
A implementação de referência nesta seção usa a criação direta de sandbox e é aplicável a agentes que toleram latência de inicialização de vários segundos.
Essa abordagem usa recursos padrão do PersistentVolumeClaim (PVC) do GKE para vincular um sandbox a um PVC preexistente que contém os dados de um usuário.
O padrão de espaço de trabalho com estado segue esta sequência de eventos:
- Provisionamento: o administrador ou orquestrador provisiona manualmente um PVC particular para cada sessão de agente usando um identificador determinista (por exemplo,
pvc-agent-1). - Referência: no recurso
Sandbox, use o campopersistentVolumeClaimno blocovolumespara especificar oclaimNameexato do volume atual. - Latência: quando o sandbox é criado, o GKE precisa anexar dinamicamente o disco do Compute Engine à VM do nó, o que gera um atraso padrão de vários segundos.
- Persistência: ao encerrar a sessão (excluindo o recurso
Sandbox), o GKE desconecta o disco, mas não destrói o PVC, o que ajuda a garantir que o estado mais recente seja preservado para a próxima sessão.
Para configurar um espaço de trabalho com estado que preserva dados entre sessões, conclua as etapas nas subseções a seguir.
Provisionar um espaço de trabalho permanente (PVC)
Crie um PersistentVolumeClaim (PVC) particular que use um identificador determinista, como pvc-agent-1.
Salve o seguinte manifesto como
pvc-agent-1.yaml:apiVersion: v1 kind: PersistentVolumeClaim metadata: name: pvc-agent-1 # Derived directly from the deterministic assignment ID namespace: default spec: accessModes: - ReadWriteOnce storageClassName: dynamic-rwo # Selects disk type compatible with the node machine family resources: requests: storage: 10GiAplique o manifesto:
kubectl apply -f pvc-agent-1.yaml
Como a classe de armazenamento usa a vinculação de volume dinâmico, o disco ainda não está anexado
a nenhum nó. Ele permanece no estado Pending até que um pod que o solicite seja
programado.
Implantar o Agent Sandbox
Implante o recurso personalizado Sandbox, referenciando o PVC determinista.
Salve o seguinte manifesto como
sandbox-agent-1.yaml:apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: sandbox-agent-1 # Traceable sandbox name namespace: default spec: podTemplate: spec: runtimeClassName: gvisor # Required automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor # Required tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: workspace-disk mountPath: /workspace # Mounts the private disk into the container resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required volumes: - name: workspace-disk persistentVolumeClaim: claimName: pvc-agent-1 # Binds this specific Sandbox to Agent 1's PVC restartPolicy: OnFailureAplique o manifesto:
kubectl apply -f sandbox-agent-1.yamlAguarde até que o sandbox esteja pronto:
kubectl wait sandbox sandbox-agent-1 \ --for=condition=Ready \ --timeout=300sO GKE verifica a capacidade do nó e anexa o disco, o que leva alguns segundos. O contêiner é inicializado dentro de um kernel do gVisor no espaço do usuário. Em um cluster do Autopilot, o sandbox pode levar vários minutos para ficar pronto, porque o GKE pode precisar criar um nó para ele.
Gravar dados do agente
Simule um agente de IA ativo executando modificações de arquivo no espaço de trabalho dele gravando um arquivo de texto no disco montado.
# Set the active Pod name
POD_NAME=sandbox-agent-1
# Write a state file to the persistent directory
kubectl exec ${POD_NAME} -- sh -c "echo 'Workspace State Saved - Agent 1' > /workspace/modified_data.txt"
# Confirm the file exists on the disk
kubectl exec ${POD_NAME} -- cat /workspace/modified_data.txt
Encerrar a sessão do agente
Para simular a redução de escala vertical ou o encerramento da sessão quando o agente ficar inativo,
exclua o recurso Sandbox, mas preserve o armazenamento subjacente.
kubectl delete sandbox sandbox-agent-1
O GKE desmonta e desconecta o disco. O PVC pvc-agent-1
permanece, preservando os dados.
Reativar a sessão do agente
Para reativar a sessão, reimplante um novo recurso Sandbox que faça referência
ao mesmo PVC e aguarde até que o sandbox esteja pronto:
kubectl apply -f sandbox-agent-1.yaml
kubectl wait sandbox sandbox-agent-1 \
--for=condition=Ready \
--timeout=300s
O disco é reconectado (com o atraso de conexão) e o contêiner é inicializado.
Verificar a preservação de dados
Inspecione o contêiner de sandbox recém-criado para verificar se os dados da sessão anterior foram preservados.
# Set the active Pod name of the new session
NEW_POD_NAME=sandbox-agent-1
# Read the file from the newly booted sandbox
kubectl exec ${NEW_POD_NAME} -- cat /workspace/modified_data.txt
A saída vai mostrar Workspace State Saved - Agent 1.
Limpar recursos
Exclua o Agent Sandbox e a reivindicação de volume permanente associada:
kubectl delete sandbox sandbox-agent-1
kubectl delete pvc pvc-agent-1
Configurar uma restauração pontual e uma transferência de propriedade
Use esse padrão para clonar conjuntos de dados para executar experimentos paralelos, depuração ou trabalho independente. O espaço de trabalho de um agente é inicializado com base em um conjunto de dados histórico (ou estado compartilhado), salvando as modificações subsequentes em uma camada gravável privada separada sem modificar o modelo base.
A implementação de referência nesta seção usa a criação direta de sandbox e é aplicável a agentes que toleram latência de inicialização de vários segundos. Essa abordagem depende do orquestrador para provisionar dinamicamente novos PersistentVolumeClaims (PVCs) de VolumeSnapshots históricos antes de iniciar uma nova sessão de sandbox.
Criar o VolumeSnapshotClass
Crie um VolumeSnapshotClass que especifique o driver CSI e a política de exclusão.
Para o Hyperdisk, use o driver pd.csi.storage.gke.io.
Salve o seguinte manifesto como
1-snapshot-class.yaml:apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: standard-rwo-snapshot driver: pd.csi.storage.gke.io deletionPolicy: DeleteAplique o manifesto:
kubectl apply -f 1-snapshot-class.yaml
Provisionar o espaço de trabalho inicial
Crie um volume em que o agente vai realizar o trabalho inicial.
Salve o seguinte manifesto como
2-source-pvc.yaml:apiVersion: v1 kind: PersistentVolumeClaim metadata: name: agent-source-pvc spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo resources: requests: storage: 10GiAplique o manifesto:
kubectl apply -f 2-source-pvc.yaml
Gerar dados de estado
Implante um pod de sandbox para gravar dados no volume.
Salve o seguinte manifesto como
3-source-sandbox.yaml:apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: agent-session-v1 namespace: default spec: podTemplate: spec: runtimeClassName: gvisor automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor # Required tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: workspace mountPath: /workspace resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required volumes: - name: workspace persistentVolumeClaim: claimName: agent-source-pvc restartPolicy: OnFailureAplique o manifesto:
kubectl apply -f 3-source-sandbox.yamlAguarde até que o sandbox esteja pronto e, em seguida, grave um arquivo de estado. O comando
synclimpa a gravação no disco para que o snapshot na próxima seção inclua o conteúdo do arquivo:kubectl wait sandbox agent-session-v1 \ --for=condition=Ready \ --timeout=300s POD_NAME=agent-session-v1 kubectl exec ${POD_NAME} -- sh -c "echo 'Point-in-Time Snapshot - v1' > /workspace/state.txt && sync"
Arquivar o estado histórico (VolumeSnapshot do CSI)
Acione um VolumeSnapshot do CSI para congelar o estado atual. Ao criar um snapshot, siga as práticas recomendadas para snapshots de disco.
Salve o seguinte manifesto como
4-volume-snapshot.yaml:apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshot metadata: name: agent-session-v1-snapshot spec: volumeSnapshotClassName: standard-rwo-snapshot source: persistentVolumeClaimName: agent-source-pvcAplique o manifesto:
kubectl apply -f 4-volume-snapshot.yamlAguarde até que o snapshot esteja pronto para uso:
kubectl wait volumesnapshot agent-session-v1-snapshot \ --for=jsonpath='{.status.readyToUse}'=true \ --timeout=600s
Restaurar o volume do snapshot
Implante um novo PVC com o dataSource apontando para o VolumeSnapshot do CSI.
Salve o seguinte manifesto como
5-restored-pvc.yaml:apiVersion: v1 kind: PersistentVolumeClaim metadata: name: agent-restored-pvc spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo dataSource: name: agent-session-v1-snapshot kind: VolumeSnapshot apiGroup: snapshot.storage.k8s.io resources: requests: storage: 10GiAplique o manifesto:
kubectl apply -f 5-restored-pvc.yaml
Iniciar a sessão restaurada do Agent Sandbox
Provisione um novo recurso Sandbox que faça referência ao PVC recém-restaurado.
Salve o seguinte manifesto como
6-restored-sandbox.yaml:apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: agent-session-v2-restored namespace: default spec: podTemplate: spec: runtimeClassName: gvisor automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor # Required tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: workspace mountPath: /workspace resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required volumes: - name: workspace persistentVolumeClaim: claimName: agent-restored-pvc restartPolicy: OnFailureAplique o manifesto:
kubectl apply -f 6-restored-sandbox.yamlAguarde até que o sandbox esteja pronto:
kubectl wait sandbox agent-session-v2-restored \ --for=condition=Ready \ --timeout=600sEsse sandbox pode levar mais tempo para ficar pronto do que o sandbox de origem, porque o GKE cria o disco com base no snapshot depois que ele está pronto.
Verificar a persistência e a restauração
Verifique se o agente pode ler os dados históricos.
NEW_POD_NAME=agent-session-v2-restored
kubectl exec ${NEW_POD_NAME} -- cat /workspace/state.txt
Saída esperada: Point-in-Time Snapshot - v1
Limpar recursos
Exclua os Agent Sandboxes, os PVCs e o VolumeSnapshot:
kubectl delete sandbox agent-session-v1
kubectl delete sandbox agent-session-v2-restored
kubectl delete pvc agent-source-pvc
kubectl delete pvc agent-restored-pvc
kubectl delete volumesnapshot agent-session-v1-snapshot
kubectl delete volumesnapshotclass standard-rwo-snapshot
Configurar um espaço de trabalho temporário
Use o padrão de espaço de trabalho temporário quando um agente precisar de um volume de armazenamento para armazenar arquivos temporários enquanto estiver ativo. Nenhum dado precisa ser preservado na exclusão do Agent Sandbox.
Configurar com inicialização em menos de um segundo
Use o Agent Sandbox em pools de aquecimento do GKE para pré-provisionar volumes vazios em segundo plano.
Definir o recurso SandboxTemplate
Defina o backup de armazenamento temporário no bloco volumeClaimTemplate.
Salve o seguinte manifesto como
stateless-template.yaml:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxTemplate metadata: name: stateless-sandbox-template namespace: default spec: podTemplate: spec: runtimeClassName: gvisor automountServiceAccountToken: false securityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: ephemeral-disk mountPath: /workspace resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required volumeClaimTemplates: - metadata: name: ephemeral-disk spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo # Selects disk type compatible with node machine family resources: requests: storage: 10Gi
Iniciar o recurso SandboxWarmPool
Salve o seguinte manifesto como
stateless-warmpool.yaml:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxWarmPool metadata: name: stateless-warmpool namespace: default spec: replicas: 2 # Keep two standby Pods with pre-attached empty disks sandboxTemplateRef: name: stateless-sandbox-templateAplique os dois manifestos:
kubectl apply -f stateless-template.yaml kubectl apply -f stateless-warmpool.yamlAguarde até que os sandboxes do pool de aquecimento estejam prontos:
kubectl wait sandboxwarmpool stateless-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sSe você criar um recurso
SandboxClaimantes que os sandboxes do pool estejam prontos, o controlador poderá criar um novo sandbox para a declaração em vez de atribuir um do pool. Em um cluster do Autopilot, os sandboxes podem levar vários minutos para ficarem prontos, porque o GKE pode precisar criar nós para eles.
Criar um recurso SandboxClaim
Defina um recurso SandboxClaim que é acionado quando um usuário inicia uma sessão.
Salve o seguinte manifesto como
stateless-sandbox-claim.yaml:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxClaim metadata: name: agent-1-claim spec: warmPoolRef: name: stateless-warmpoolAplique o manifesto:
kubectl apply -f stateless-sandbox-claim.yaml
Verificar a execução em menos de um segundo
Aguarde até que a declaração esteja pronta, capture o nome do pod do Agent Sandbox e
verifique se o diretório /workspace está montado e pronto para uso imediato:
kubectl wait sandboxclaim agent-1-claim --for=condition=Ready --timeout=300s
export POD_NAME=$(kubectl get sandboxclaim agent-1-claim -o jsonpath='{.status.sandbox.name}')
kubectl exec ${POD_NAME} -- ls -la /workspace
Encerrar a sessão do agente
Para encerrar a sessão do agente, exclua o recurso SandboxClaim. A exclusão da
reivindicação também exclui o sandbox reivindicado e o volume dele:
kubectl delete sandboxclaim agent-1-claim
Limpar recursos
Exclua os recursos SandboxWarmPool e SandboxTemplate:
kubectl delete sandboxwarmpool stateless-warmpool
kubectl delete sandboxtemplate stateless-sandbox-template
Configurar com inicialização de vários segundos
Para implementar um espaço de trabalho temporário que tolera latência de vários segundos, use a criação direta do Agent Sandbox sem um pool de inicialização.
Definir um Agent Sandbox sem estado
Salve o seguinte manifesto como
sandbox-direct-stateless.yaml:apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: sandbox-direct-stateless namespace: default spec: podTemplate: spec: runtimeClassName: gvisor automountServiceAccountToken: false securityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000 # Grant group access to the volume nodeSelector: sandbox.gke.io/runtime: gvisor tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" containers: - name: agent image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 volumeMounts: - name: ephemeral-disk mountPath: /workspace resources: limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required restartPolicy: OnFailure volumeClaimTemplates: - metadata: name: ephemeral-disk spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo resources: requests: storage: 10Gi
Implantar o Agent Sandbox
Para provisionar dinamicamente o disco e anexá-lo ao nó programado, aplique o manifesto:
kubectl apply -f sandbox-direct-stateless.yaml
Verificar a latência e a execução da inicialização
Monitore o status do pod para observar o atraso de anexação antes que ele
mude para o estado Running:
kubectl get pods -w
Quando o pod estiver em execução, pressione Control+C para parar de assistir.
Capture o nome do pod e verifique se o diretório /workspace está disponível:
POD_NAME=sandbox-direct-stateless
kubectl exec ${POD_NAME} -- ls -la /workspace
Encerrar sessão do agente
Exclua o recurso Sandbox para encerrar automaticamente o pod e destruir
o armazenamento temporário dele:
kubectl delete sandbox sandbox-direct-stateless
A seguir
- Saiba mais sobre o Agent Sandbox no GKE.
- Saiba mais sobre como isolar a execução de código de IA com o Agent Sandbox no GKE.
- Saiba como salvar e restaurar o Agent Sandbox em ambientes do GKE com snapshots de pod.