Administra Agent Sandbox en el almacenamiento de GKE

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:

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 accessModes a ReadWriteMany y 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:

  1. Define las variables de entorno.
  2. Cree un clúster de GKE
  3. Instala Agent Sandbox
  4. 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:

  1. 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).
  2. Referencia: En el recurso Sandbox, usas el campo persistentVolumeClaim dentro del bloque volumes para especificar el claimName exacto del volumen existente.
  3. 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.
  4. 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.

  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: 10Gi
    
  2. Aplica 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.

  1. 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: OnFailure
    
  2. Aplica el manifiesto

    kubectl apply -f sandbox-agent-1.yaml
    
  3. Espera hasta que la zona de pruebas esté lista:

    kubectl wait sandbox sandbox-agent-1 \
        --for=condition=Ready \
        --timeout=300s
    

    GKE 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.

  1. 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: Delete
    
  2. Aplica 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.

  1. 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: 10Gi
    
  2. Aplica 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.

  1. 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: OnFailure
    
  2. Aplica el manifiesto

    kubectl apply -f 3-source-sandbox.yaml
    
  3. Espera hasta que la zona de pruebas esté lista y, luego, escribe un archivo de estado. El comando sync vací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.

  1. 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-pvc
    
  2. Aplica el manifiesto

    kubectl apply -f 4-volume-snapshot.yaml
    
  3. Espera 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.

  1. 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: 10Gi
    
  2. Aplica 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.

  1. 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: OnFailure
    
  2. Aplica el manifiesto

    kubectl apply -f 6-restored-sandbox.yaml
    
  3. Espera hasta que la zona de pruebas esté lista:

    kubectl wait sandbox agent-session-v2-restored \
        --for=condition=Ready \
        --timeout=600s
    

    Esta 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.

  1. 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

  1. 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-template
    
  2. Aplica ambos manifiestos:

    kubectl apply -f stateless-template.yaml
    kubectl apply -f stateless-warmpool.yaml
    
  3. Espera 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=600s
    

    Si creas un recurso SandboxClaim antes 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.

  1. 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-warmpool
    
  2. Aplica 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

  1. 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?