En este documento, se proporcionan implementaciones de referencia para administrar el almacenamiento de Agent Sandbox en GKE adaptadas a las necesidades del ciclo de vida de los datos de tus agentes.
Según las necesidades del ciclo de vida de los datos de tus agentes, elige una de las siguientes configuraciones:
- Configura un espacio de trabajo con estado
- Configura una restauración de un momento determinado y una transferencia de propiedad
- Configura un espacio de trabajo efímero
Para obtener más información sobre cómo elegir una solución de almacenamiento, consulta Elige el almacenamiento para las cargas de trabajo de agentes de IA.
En el siguiente documento, se usa la StorageClass dynamic-rwo para la selección automática del tipo de disco
con el objetivo de aprovisionar discos compatibles con los tipos de máquinas de los nodos en los que
se programan los Pods de Agent Sandbox en GKE. Para garantizar
que GKE aprovisione volúmenes de Hyperdisk Balanced para
el almacenamiento de tus agentes, debes programar tu Agent Sandbox en
Pods de GKE en los nodos de familias de máquinas
compatibles, como
N4. De lo contrario, GKE recurre a pd-balanced.
En este documento, se implementa el modo de acceso a los datos de Espacio de trabajo aislado privado con
el acceso ReadWriteOnce (RWO). En este modo, un agente se inicia con un
directorio de almacenamiento aislado privado al que tiene acceso exclusivo de lectura y escritura.
A menos que se especifique lo contrario, las implementaciones de referencia de este documento usan la creación directa de la zona de pruebas, que se aplica a los agentes que toleran una latencia de inicio de varios segundos. Para lograr una latencia de inicio de menos de un segundo para los espacios de trabajo de restablecimiento con estado o en un momento determinado, debes usar Agent Sandbox en grupos de preparación de GKE. Vincular el almacenamiento a un Pod de grupo preparado reclamado requiere una secuencia de comandos personalizada y un DaemonSet con privilegios. Para ver una implementación de referencia, consulta este ejemplo de GitHub.
Modos de acceso alternativos
Para admitir modos de acceso alternativos, puedes modificar las definiciones de volumen y de instantánea en los parámetros de configuración:
- Espacio de trabajo colaborativo: Cambia
accessModesaReadWriteManyy usa una StorageClass compatible con RWX, como Filestore Multishares (Enterprise) (enterprise-multishare-rwx). - Espacio de trabajo de ramificación de exploración: Activa la carpeta de plantillas como de solo lectura
y proporciona un bloc de notas independiente en el que se pueda escribir. Para la plantilla base, debes
usar un almacenamiento que admita varios adjuntos de solo lectura, como
Hyperdisk ML
con el modo de acceso
ReadOnlyMany(ROX) o los recursos compartidos múltiples de Filestore con el modo de acceso RWX.
Antes de comenzar
Asegúrate de tener un clúster de GKE que tenga instalado el controlador de Agent Sandbox. De lo contrario, completa solo las siguientes secciones de Instala Agent Sandbox en GKE y, luego, regresa a este documento:
- Define las variables de entorno.
- Cree un clúster de GKE
- Instala Agent Sandbox
- Aplica la política de seguridad recomendada
Si completaste la sección Implementa un entorno de zona de pruebas de ese documento, borra los recursos de muestra que se crearon para que tus nodos tengan suficiente capacidad para las zonas de pruebas de este 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
Configura un espacio de trabajo con estado
Usa este patrón para conservar el estado más reciente de los archivos de un agente. Es útil cuando tu agente debe conservar el estado cuando la sesión del agente se pausa o finaliza (se borra la zona de pruebas del agente) y restablecer los datos del estado más reciente cuando se activa la sesión del agente (se vuelve a crear la zona de pruebas del agente).
La implementación de referencia de esta sección usa la creación directa de la zona de pruebas y se aplica a los agentes que toleran una latencia de inicio de varios segundos.
Este enfoque usa recursos estándar de PersistentVolumeClaim (PVC) de GKE para vincular una zona de pruebas a una PVC preexistente que contiene los datos de un usuario.
El patrón de espacio de trabajo con estado sigue esta secuencia de eventos:
- Aprovisionamiento: El administrador o el organizador aprovisionan de forma manual una
PVC privada para cada sesión de agente con un identificador determinístico (por
ejemplo,
pvc-agent-1). - Referencia: En el recurso
Sandbox, usas el campopersistentVolumeClaimdentro del bloquevolumespara especificar elclaimNameexacto del volumen existente. - Latencia: Cuando se crea la zona de pruebas, GKE debe conectar de forma dinámica el disco de Compute Engine a la VM del nodo, lo que genera una demora estándar de varios segundos.
- Persistencia: Cuando finaliza la sesión (se borra el recurso
Sandbox), GKE desconecta el disco, pero no destruye la PVC, lo que ayuda a garantizar que se conserve el estado más reciente para la próxima sesión.
Para configurar un espacio de trabajo con estado que conserve los datos entre sesiones, completa los pasos que se indican en las siguientes subsecciones.
Aprovisiona un espacio de trabajo persistente (PVC)
Crea una PersistentVolumeClaim (PVC) privada que use un identificador determinístico, como pvc-agent-1.
Guarda el siguiente manifiesto 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: 10GiAplica el manifiesto
kubectl apply -f pvc-agent-1.yaml
Debido a que la clase de almacenamiento usa la vinculación dinámica de volúmenes, el disco aún no está conectado
a ningún nodo. Permanece en estado Pending hasta que se programa un Pod que lo solicita.
Implementa Agent Sandbox
Implementa el recurso personalizado Sandbox, que hace referencia a la PVC determinística.
Guarda el siguiente manifiesto 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: OnFailureAplica el manifiesto
kubectl apply -f sandbox-agent-1.yamlEspera hasta que la zona de pruebas esté lista:
kubectl wait sandbox sandbox-agent-1 \ --for=condition=Ready \ --timeout=300sGKE verifica la capacidad del nodo y adjunta el disco, lo que tarda unos segundos. El contenedor se inicializa dentro de un kernel de gVisor en el espacio del usuario. En un clúster de Autopilot, la zona de pruebas puede tardar varios minutos en estar lista, ya que es posible que GKE deba crear un nodo para ella.
Escribe datos del agente
Simula un agente de IA activo que ejecuta modificaciones de archivos dentro de su espacio de trabajo escribiendo un archivo de texto en el disco activado.
# 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
Finaliza la sesión del agente
Para simular la reducción de escala o la finalización de la sesión cuando el agente queda inactivo,
borra el recurso Sandbox, pero conserva el almacenamiento subyacente.
kubectl delete sandbox sandbox-agent-1
GKE desactiva y desconecta el disco. La PVC pvc-agent-1
permanece, lo que conserva los datos.
Reactiva la sesión del agente
Para reactivar la sesión, vuelve a implementar un recurso Sandbox nuevo que haga referencia
a la misma PVC y, luego, espera hasta que la zona de pruebas esté lista:
kubectl apply -f sandbox-agent-1.yaml
kubectl wait sandbox sandbox-agent-1 \
--for=condition=Ready \
--timeout=300s
El disco se vuelve a conectar (lo que genera la demora de conexión) y el contenedor se inicia.
Verifica la preservación de datos
Inspecciona el contenedor de la zona de pruebas recién creado para verificar que se hayan conservado los datos de la sesión anterior.
# 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
El resultado debería mostrar Workspace State Saved - Agent 1.
Limpia los recursos
Borra la Agent Sandbox y la reclamación de volumen persistente asociada:
kubectl delete sandbox sandbox-agent-1
kubectl delete pvc pvc-agent-1
Configurar un restablecimiento de un momento determinado y una transferencia de propiedad
Usa este patrón para clonar conjuntos de datos y ejecutar experimentos paralelos, depurar o trabajar de forma independiente. El espacio de trabajo de un agente se inicializa a partir de un conjunto de datos históricos (o estado compartido), lo que guarda las modificaciones posteriores en una capa de escritura privada independiente sin modificar la plantilla base.
La implementación de referencia de esta sección usa la creación directa de la zona de pruebas y se aplica a los agentes que toleran una latencia de inicio de varios segundos. Este enfoque depende de que el organizador aprovisione de forma dinámica nuevas PersistentVolumeClaims (PVC) a partir de VolumeSnapshots históricos antes de iniciar una nueva sesión de zona de pruebas.
Crea la VolumeSnapshotClass
Crea un VolumeSnapshotClass que especifique el controlador CSI y la política de eliminación.
Para Hyperdisk, usa el controlador pd.csi.storage.gke.io.
Guarda el siguiente manifiesto 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: DeleteAplica el manifiesto
kubectl apply -f 1-snapshot-class.yaml
Aprovisiona el espacio de trabajo inicial
Crea un volumen en el que el agente realizará su trabajo inicial.
Guarda el siguiente manifiesto como
2-source-pvc.yaml:apiVersion: v1 kind: PersistentVolumeClaim metadata: name: agent-source-pvc spec: accessModes: ["ReadWriteOnce"] storageClassName: dynamic-rwo resources: requests: storage: 10GiAplica el manifiesto
kubectl apply -f 2-source-pvc.yaml
Genera datos de estado
Implementa un Pod de zona de pruebas para escribir datos en el volumen.
Guarda el siguiente manifiesto 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: OnFailureAplica el manifiesto
kubectl apply -f 3-source-sandbox.yamlEspera hasta que la zona de pruebas esté lista y, luego, escribe un archivo de estado. El comando
syncvacía la escritura en el disco para que la instantánea de la siguiente sección incluya el contenido del archivo: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"
Archiva el estado histórico (VolumeSnapshot de CSI)
Activa un VolumeSnapshot de CSI para congelar el estado actual. Cuando tomes una instantánea, sigue las prácticas recomendadas para las instantáneas de discos.
Guarda el siguiente manifiesto 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-pvcAplica el manifiesto
kubectl apply -f 4-volume-snapshot.yamlEspera hasta que la instantánea esté lista para usarse:
kubectl wait volumesnapshot agent-session-v1-snapshot \ --for=jsonpath='{.status.readyToUse}'=true \ --timeout=600s
Restablece el volumen a partir de la instantánea
Implementa una PVC nueva con su dataSource que apunte al VolumeSnapshot de CSI.
Guarda el siguiente manifiesto 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: 10GiAplica el manifiesto
kubectl apply -f 5-restored-pvc.yaml
Inicia la sesión de Agent Sandbox restablecida
Aprovisiona un recurso Sandbox nuevo que haga referencia a la PVC restablecida recientemente.
Guarda el siguiente manifiesto 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: OnFailureAplica el manifiesto
kubectl apply -f 6-restored-sandbox.yamlEspera hasta que la zona de pruebas esté lista:
kubectl wait sandbox agent-session-v2-restored \ --for=condition=Ready \ --timeout=600sEsta zona de pruebas puede tardar más en estar lista que la zona de pruebas de origen, ya que GKE crea su disco a partir de la instantánea después de que esta está lista.
Verifica la persistencia y el restablecimiento
Verifica que el agente pueda leer los datos históricos.
NEW_POD_NAME=agent-session-v2-restored
kubectl exec ${NEW_POD_NAME} -- cat /workspace/state.txt
Resultado esperado: Point-in-Time Snapshot - v1
Limpia los recursos
Borra los Agent Sandboxes, las PVC y el 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
Configura un espacio de trabajo efímero
Usa el patrón de espacio de trabajo efímero cuando un agente necesite un volumen de almacenamiento para almacenar archivos temporales mientras el agente esté activo. No es necesario conservar ningún dato cuando se borra Agent Sandbox.
Configura con un inicio de menos de un segundo
Usa Agent Sandbox en grupos de preparación de GKE para aprovisionar de forma previa volúmenes vacíos en segundo plano.
Define el recurso SandboxTemplate
Define el respaldo de almacenamiento efímero dentro del bloque volumeClaimTemplate.
Guarda el siguiente manifiesto 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
Inicia el recurso SandboxWarmPool
Guarda el siguiente manifiesto 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-templateAplica ambos manifiestos:
kubectl apply -f stateless-template.yaml kubectl apply -f stateless-warmpool.yamlEspera hasta que las zonas de pruebas del grupo de preparación estén listas:
kubectl wait sandboxwarmpool stateless-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sSi creas un recurso
SandboxClaimantes de que las zonas de pruebas del grupo estén listas, el controlador podría crear una zona de pruebas nueva para la reclamación en lugar de asignar una del grupo. En un clúster de Autopilot, las zonas de pruebas pueden tardar varios minutos en estar listas, ya que es posible que GKE deba crear nodos para ellas.
Crea un recurso SandboxClaim
Define un recurso SandboxClaim que se active cuando un usuario inicie una sesión.
Guarda el siguiente manifiesto como
stateless-sandbox-claim.yaml:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxClaim metadata: name: agent-1-claim spec: warmPoolRef: name: stateless-warmpoolAplica el manifiesto
kubectl apply -f stateless-sandbox-claim.yaml
Verifica la ejecución en menos de un segundo
Espera hasta que la reclamación esté lista, captura el nombre del Pod de Agent Sandbox y, luego,
verifica que el directorio /workspace esté activado y listo para su uso inmediato:
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
Finaliza la sesión del agente
Para finalizar la sesión del agente, borra el recurso SandboxClaim. Si borras la
reclamación, también se borrará la zona de pruebas reclamada y su volumen:
kubectl delete sandboxclaim agent-1-claim
Limpia los recursos
Borra los recursos SandboxWarmPool y SandboxTemplate:
kubectl delete sandboxwarmpool stateless-warmpool
kubectl delete sandboxtemplate stateless-sandbox-template
Configura con un inicio de varios segundos
Para implementar un espacio de trabajo efímero que tolere una latencia de varios segundos, usa la creación directa de Agent Sandbox sin un grupo de preparación.
Define una zona de pruebas del agente sin estado
Guarda el siguiente manifiesto 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
Implementa Agent Sandbox
Para aprovisionar el disco de forma dinámica y conectarlo al nodo programado, aplica el manifiesto:
kubectl apply -f sandbox-direct-stateless.yaml
Verifica la latencia de inicio y la ejecución
Supervisa el estado del Pod para observar la demora de conexión antes de que el Pod
cambie al estado Running:
kubectl get pods -w
Cuando el Pod se esté ejecutando, presiona Control + C para detener la observación.
Captura el nombre del Pod y verifica que el directorio /workspace esté disponible:
POD_NAME=sandbox-direct-stateless
kubectl exec ${POD_NAME} -- ls -la /workspace
Finalizar la sesión del agente
Borra el recurso Sandbox para finalizar automáticamente el Pod y destruir
su almacenamiento efímero:
kubectl delete sandbox sandbox-direct-stateless
¿Qué sigue?
- Obtén más información sobre Agent Sandbox en GKE.
- Obtén más información para aislar la ejecución de código de IA con Agent Sandbox en GKE.
- Obtén información para guardar y restablecer Agent Sandbox en entornos de GKE con instantáneas de Pods.