Administra el almacenamiento de la zona de pruebas del agente

En este documento, se proporcionan implementaciones de referencia para administrar el almacenamiento de las zonas de pruebas del agente adaptadas a las necesidades del ciclo de vida de datos de tus agentes.

Según las necesidades del ciclo de vida de 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 para aprovisionar discos compatibles con los tipos de máquinas de los nodos en los que se programan los pods de la zona de pruebas del agente. Para asegurarte de que GKE aprovisione volúmenes de Hyperdisk Balanced para el almacenamiento de tus agentes, debes programar las zonas de pruebas del agente 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 Lugar de trabajo aislado privado mediante 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 la latencia de inicio de varios segundos. Para lograr una latencia de inicio inferior a un segundo para los lugares de trabajo con estado o de restauración de un momento determinado, debes usar los grupos de nodos en espera de la zona de pruebas del agente de GKE. Para vincular el almacenamiento a un pod de grupo de nodos en espera reclamado, se requieren secuencias de comandos personalizadas y un DaemonSet con privilegios. Para obtener 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 las configuraciones:

  • Lugar de trabajo colaborativo: cambia accessModes a ReadWriteMany y usa una StorageClass compatible con RWX, como Filestore Multishares (Enterprise) (enterprise-multishare-rwx).
  • Lugar de trabajo de bifurcación de exploración: Activa la carpeta de la plantilla como de solo lectura y proporciona un bloc de notas borrador escribible independiente. Para la plantilla base, debes usar almacenamiento que admita varios archivos adjuntos de solo lectura, como Hyperdisk ML con ReadOnlyMany (ROX) modo de acceso o Filestore Multishares con el modo de acceso RWX.

Antes de comenzar

Habilita la zona de pruebas del agente en tu clúster.

Configura un lugar 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 se pausa o finaliza la sesión del agente (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 la 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 lugar de trabajo con estado sigue esta secuencia de eventos:

  1. Aprovisionamiento: El administrador o el orquestador aprovisionan de forma manual una PVC privada para cada sesión del agente con un identificador determinista (por ejemplo, pvc-agent-1).
  2. Referencia: En el recurso de la zona de pruebas, usas el persistentVolumeClaim campo dentro del volumes bloque para especificar el exacto claimName del volumen existente.
  3. Latencia: Cuando se crea la zona de pruebas, GKE debe adjuntar 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 la zona de pruebas), 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 lugar de trabajo con estado que conserve los datos entre sesiones, completa los pasos de las siguientes subsecciones.

Aprovisiona un lugar de trabajo persistente (PVC)

Crea una PersistentVolumeClaim (PVC) privada que use un identificador determinista, 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 de volumen dinámico, el disco aún no está conectado a ningún nodo. Permanece en estado Pending hasta que se programe un pod que lo solicite.

Implementa la zona de pruebas del agente

Implementa el recurso personalizado de la zona de pruebas, haciendo referencia a la PVC determinista.

  1. Guarda el siguiente manifiesto como sandbox-agent-1.yaml:

    apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-agent-1 # Traceable sandbox name
  namespace: default
spec:
  replicas: 1
  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

GKE verifica la capacidad del nodo y conecta el disco, lo que tarda unos segundos. El contenedor se inicializa dentro de un kernel de gVisor del espacio de usuario.

Escribe datos del agente

Simula un agente de IA activo que ejecuta modificaciones de archivos dentro de su lugar 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 o la finalización de la sesión cuando el agente está inactivo, borra el recurso de la zona de pruebas, pero conserva el almacenamiento subyacente.

kubectl delete sandbox sandbox-agent-1

GKE desactiva y desconecta el disco. La PVC pvc-agent-1 permanece y conserva los datos.

Reactiva la sesión del agente

Para reactivar la sesión, vuelve a implementar un recurso de zona de pruebas nuevo que haga referencia a la misma PVC.

kubectl apply -f sandbox-agent-1.yaml

El disco se vuelve a conectar (lo que genera la demora de conexión) y se inicia el contenedor.

Verifica la conservación de datos

Inspecciona el contenedor de la zona de pruebas recién creado para verificar que se conserven 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 -it $NEW_POD_NAME -- cat /workspace/modified_data.txt

El resultado debería mostrar Workspace State Saved - Agent 1.

Limpia los recursos

Borra la zona de pruebas del agente y la reclamación de volumen persistente asociada:

kubectl delete sandbox sandbox-agent-1
kubectl delete pvc pvc-agent-1

Configura una restauración de un momento determinado y una transferencia de propiedad

Usa este patrón para clonar conjuntos de datos para ejecutar experimentos paralelos, depurar o trabajar de forma independiente. El lugar de trabajo de un agente se inicializa a partir de un conjunto de datos histórico (o estado compartido), lo que guarda las modificaciones posteriores en una capa escribible 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 la latencia de inicio de varios segundos. Este enfoque se basa en el orquestador para aprovisionar de forma dinámica PersistentVolumeClaims (PVCs) nuevas a partir de VolumeSnapshots históricas antes de iniciar una sesión de zona de pruebas nueva.

Crea la VolumeSnapshotClass

Crea una 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 lugar 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/v1alpha1
kind: Sandbox
metadata:
  name: agent-session-v1
  namespace: default
spec:
  replicas: 1
  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 a que el pod esté en ejecución y, luego, escribe un archivo de estado:

    POD_NAME=agent-session-v1
kubectl exec $POD_NAME -- sh -c "echo 'Point-in-Time Snapshot - v1' > /workspace/state.txt"

Archiva el estado histórico (VolumeSnapshot de CSI)

Activa un VolumeSnapshot de CSI para inmovilizar 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

Restablece el volumen a partir de la instantánea

Implementa una PVC nueva con su dataSource que apunte a la 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 la zona de pruebas del agente restablecida

Aprovisiona un recurso de zona de pruebas nuevo que haga referencia a la PVC recién restablecida.

  1. Guarda el siguiente manifiesto como 6-restored-sandbox.yaml:

    apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: agent-session-v2-restored
  namespace: default
spec:
  replicas: 1
  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

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 las zonas de pruebas del agente, las PVCs y la 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 lugar de trabajo efímero

Usa el patrón de lugar de trabajo efímero cuando un agente necesita un volumen de almacenamiento para almacenar archivos temporales mientras está activo. No es necesario conservar datos cuando se borra la zona de pruebas del agente.

Configura con inicio inferior a un segundo

Usa los grupos de nodos en espera de la zona de pruebas del agente para aprovisionar previamente volúmenes vacíos en segundo plano.

Define la SandboxTemplate

Define el almacenamiento efímero de respaldo dentro del bloque volumeClaimTemplate.

  1. Guarda el siguiente manifiesto como stateless-template.yaml:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
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 grupo de nodos en espera de la zona de pruebas

  1. Guarda el siguiente manifiesto como stateless-warmpool.yaml:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: stateless-warmpool
  namespace: default
spec:
  replicas: 5 # Keep five 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

Reclama la zona de pruebas

Define una SandboxClaim que se active cuando un usuario inicia una sesión.

  1. Guarda el siguiente manifiesto como stateless-sandbox-claim.yaml:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: agent-1-claim
spec:
  sandboxTemplateRef:
    name: stateless-sandbox-template

  2. Aplica el manifiesto

    kubectl apply -f stateless-sandbox-claim.yaml

Verifica la ejecución inferior a un segundo

Captura el nombre del pod de la zona de pruebas del agente y verifica que el directorio /workspace esté activado y listo para usarse de inmediato:

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 y liberar la zona de pruebas reclamada, borra el recurso SandboxClaim:

kubectl delete sandboxclaim agent-1-claim

Limpia los recursos

Borra el grupo de nodos en espera de la zona de pruebas y la plantilla de la zona de pruebas:

kubectl delete sandboxwarmpool stateless-warmpool
kubectl delete sandboxtemplate stateless-sandbox-template

Configura con inicio de varios segundos

Para implementar un lugar de trabajo efímero que tolere la latencia de varios segundos, usa la creación directa de la zona de pruebas del agente sin un grupo de nodos en espera.

Define una zona de pruebas del agente sin estado

  1. Guarda el siguiente manifiesto como sandbox-direct-stateless.yaml:

    apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-direct-stateless
  namespace: default
spec:
  replicas: 1
  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 la zona de pruebas del agente

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 pase al estado Running:

kubectl get pods -w

Después de que el pod esté en ejecució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

Finaliza la sesión del agente

Borra el recurso de la zona de pruebas para finalizar automáticamente el pod y destruir su almacenamiento efímero:

kubectl delete sandbox sandbox-direct-stateless

¿Qué sigue?