Gestisci la sandbox dell'agente nello spazio di archiviazione GKE

Questo documento fornisce implementazioni di riferimento per la gestione dello spazio di archiviazione per Agent Sandbox su GKE, personalizzate in base alle esigenze del ciclo di vita dei dati degli agenti.

A seconda delle esigenze del ciclo di vita dei dati degli agenti, scegli una delle seguenti configurazioni:

Per saperne di più sulla scelta di una soluzione di archiviazione, consulta Scegli lo spazio di archiviazione per i workload degli agenti AI.

Il seguente documento utilizza la classe di archiviazione dynamic-rwo per la selezione automatica del tipo di disco per eseguire il provisioning di dischi compatibili con i tipi di macchina dei nodi in cui sono pianificati i pod Agent Sandbox su GKE. Per garantire che GKE predisponga volumi Hyperdisk Balanced per l'archiviazione degli agenti, è necessario pianificare l'Agent Sandbox su Pod GKE sui nodi delle famiglie di macchine compatibili con , come N4; altrimenti, GKE ripiega su pd-balanced.

Questo documento implementa la modalità di accesso ai dati Private Isolated Workspace utilizzando l'accesso ReadWriteOnce (RWO). In questa modalità, un agente si avvia con una directory di archiviazione isolata privata a cui ha accesso esclusivo in lettura e scrittura.

Salvo diversa indicazione, le implementazioni di riferimento in questo documento utilizzano la creazione diretta della sandbox, applicabile agli agenti che tollerano una latenza di avvio di più secondi. Per ottenere una latenza di avvio inferiore al secondo per gli spazi di lavoro di ripristino stateful o point-in-time, devi utilizzare Agent Sandbox sui pool di warm-up GKE. L'associazione dello spazio di archiviazione a un pod del pool caldo rivendicato richiede uno script personalizzato e un DaemonSet con privilegi. Per un'implementazione di riferimento, consulta questo esempio di GitHub.

Modalità di accesso alternative

Per supportare modalità di accesso alternative, puoi modificare le definizioni di volumi e snapshot nelle configurazioni:

  • Spazio di lavoro collaborativo: modifica accessModes in ReadWriteMany e utilizza una classe StorageClass compatibile con RWX, ad esempio Filestore Multishares (Enterprise) (enterprise-multishare-rwx).
  • Area di lavoro di branching dell'esplorazione: monta la cartella del modello in modalità di sola lettura e fornisce un blocco note scrivibile separato. Per il template di base, devi utilizzare uno spazio di archiviazione che supporti più collegamenti di sola lettura, ad esempio Hyperdisk ML con modalità di accesso ReadOnlyMany (ROX) o condivisioni multiple di Filestore con modalità di accesso RWX.

Prima di iniziare

Assicurati di avere un cluster GKE con il controller Agent Sandbox installato. In caso contrario, completa solo le seguenti sezioni di Installa Agent Sandbox su GKE, quindi torna a questo documento:

  1. Definisci le variabili di ambiente
  2. Crea un cluster GKE
  3. Installa Agent Sandbox
  4. Applica la policy di sicurezza consigliata

Se hai completato la sezione Esegui il deployment di un ambiente con sandbox di quel documento, elimina le risorse di esempio create in modo che i nodi abbiano capacità sufficiente per le sandbox in questo 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 workspace stateful

Utilizza questo pattern per conservare lo stato più recente dei file di un agente. È utile quando l'agente deve conservare lo stato quando la sessione dell'agente viene messa in pausa o terminata (Agent Sandbox viene eliminato) e ripristinare i dati dall'ultimo stato quando la sessione dell'agente viene attivata (Agent Sandbox viene ricreato).

L'implementazione di riferimento in questa sezione utilizza la creazione diretta della sandbox ed è applicabile agli agenti che tollerano una latenza di avvio di più secondi.

Questo approccio utilizza risorse PersistentVolumeClaim (PVC) GKE standard per collegare una sandbox a un PVC preesistente contenente i dati di un utente.

Il pattern dello spazio di lavoro stateful segue questa sequenza di eventi:

  1. Provisioning: l'amministratore o l'orchestratore esegue manualmente il provisioning di un PVC privato per ogni sessione dell'agente utilizzando un identificatore deterministico (ad esempio pvc-agent-1).
  2. Riferimento: nella risorsa Sandbox, utilizzi il campo persistentVolumeClaim all'interno del blocco volumes per specificare l'esatto claimName del volume esistente.
  3. Latenza: quando viene creata la sandbox, GKE deve collegare dinamicamente il disco di Compute Engine alla VM del nodo, il che comporta un ritardo standard di più secondi.
  4. Persistenza: al termine della sessione (eliminazione della risorsa Sandbox), GKE scollega il disco, ma non distrugge il PVC, il che contribuisce a garantire che lo stato più recente venga conservato per la sessione successiva.

Per configurare un workspace stateful che conserva i dati tra le sessioni, completa i passaggi descritti nelle sezioni seguenti.

Esegui il provisioning di uno spazio di lavoro permanente (PVC)

Crea un PersistentVolumeClaim (PVC) privato che utilizza un identificatore deterministico, ad esempio pvc-agent-1.

  1. Salva il seguente manifest come 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. Applica il manifest:

    kubectl apply -f pvc-agent-1.yaml
    

Poiché la classe di archiviazione utilizza l'associazione dinamica dei volumi, il disco non è ancora collegato a nessun nodo. Rimane in stato Pending finché non viene pianificato un pod che lo richiede.

Esegui il deployment di Agent Sandbox

Esegui il deployment della risorsa personalizzata Sandbox, facendo riferimento alla PVC deterministica.

  1. Salva il seguente manifest come 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. Applica il manifest:

    kubectl apply -f sandbox-agent-1.yaml
    
  3. Attendi che la sandbox sia pronta:

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

    GKE verifica la capacità del nodo e collega il disco, un'operazione che richiede alcuni secondi. Il container viene inizializzato all'interno di un kernel gVisor nello spazio utente. In un cluster Autopilot, la sandbox può richiedere diversi minuti per essere pronta, perché GKE potrebbe dover creare un nodo per questa.

Scrivere i dati dall'agente

Simula un agente AI attivo che esegue modifiche ai file all'interno del suo workspace scrivendo un file di testo sul disco montato.

# 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

Termina la sessione con l'agente

Per simulare lo scale down o la terminazione della sessione quando l'agente diventa inattivo, elimina la risorsa Sandbox, ma conserva lo spazio di archiviazione sottostante.

kubectl delete sandbox sandbox-agent-1

GKE smonta e scollega il disco. Il PVC pvc-agent-1 rimane, preservando i dati.

Riattiva la sessione dell'agente

Per riattivare la sessione, esegui nuovamente il deployment di una nuova risorsa Sandbox che fa riferimento alla stessa PVC, quindi attendi che la sandbox sia pronta:

kubectl apply -f sandbox-agent-1.yaml

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

Il disco viene ricollegato (con un ritardo di collegamento) e il container viene avviato.

Verifica la conservazione dei dati

Ispeziona il container della sandbox appena creato per verificare che i dati della sessione precedente siano stati conservati.

# 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

L'output dovrebbe mostrare Workspace State Saved - Agent 1.

Esegui la pulizia delle risorse

Elimina l'Agent Sandbox e la richiesta di volume permanente associata:

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

Configura un ripristino point-in-time e un trasferimento di proprietà

Utilizza questo pattern per clonare i set di dati per eseguire esperimenti paralleli, eseguire il debug o lavorare in modo indipendente. Il workspace di un agente viene inizializzato da un set di dati storico (o stato condiviso), salvando le modifiche successive in un livello scrivibile privato separato senza modificare il modello di base.

L'implementazione di riferimento in questa sezione utilizza la creazione diretta della sandbox ed è applicabile agli agenti che tollerano una latenza di avvio di più secondi. Questo approccio si basa sull'orchestratore per eseguire il provisioning dinamico di nuovi PersistentVolumeClaim (PVC) da VolumeSnapshot storici prima di avviare una nuova sessione della sandbox.

Crea la classe VolumeSnapshotClass

Crea un oggetto VolumeSnapshotClass che specifica il driver CSI e la politica di cancellazione. Per Hyperdisk, utilizza il driver pd.csi.storage.gke.io.

  1. Salva il seguente manifest come 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. Applica il manifest:

    kubectl apply -f 1-snapshot-class.yaml
    

Esegui il provisioning del workspace iniziale

Crea un volume in cui l'agente eseguirà il suo lavoro iniziale.

  1. Salva il seguente manifest come 2-source-pvc.yaml:

    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: agent-source-pvc
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: dynamic-rwo
      resources:
        requests:
          storage: 10Gi
    
  2. Applica il manifest:

    kubectl apply -f 2-source-pvc.yaml
    

Genera dati di stato

Esegui il deployment di un pod sandbox per scrivere dati nel volume.

  1. Salva il seguente manifest come 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. Applica il manifest:

    kubectl apply -f 3-source-sandbox.yaml
    
  3. Attendi che la sandbox sia pronta, quindi scrivi un file di stato. Il comando sync forza la scrittura su disco in modo che lo snapshot nella sezione successiva includa i contenuti del file:

    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"
    

Archivia lo stato storico (CSI VolumeSnapshot)

Attiva un VolumeSnapshot CSI per bloccare lo stato attuale. Quando acquisisci uno snapshot, segui le best practice per gli snapshot dei dischi.

  1. Salva il seguente manifest come 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. Applica il manifest:

    kubectl apply -f 4-volume-snapshot.yaml
    
  3. Attendi che lo snapshot sia pronto per l'uso:

    kubectl wait volumesnapshot agent-session-v1-snapshot \
        --for=jsonpath='{.status.readyToUse}'=true \
        --timeout=600s
    

Ripristina il volume dallo snapshot

Esegui il deployment di una nuova PVC con il relativo dataSource che punta al CSI VolumeSnapshot.

  1. Salva il seguente manifest come 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. Applica il manifest:

    kubectl apply -f 5-restored-pvc.yaml
    

Avvia la sessione di Agent Sandbox ripristinata

Esegui il provisioning di una nuova risorsa Sandbox che faccia riferimento al PVC appena ripristinato.

  1. Salva il seguente manifest come 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. Applica il manifest:

    kubectl apply -f 6-restored-sandbox.yaml
    
  3. Attendi che la sandbox sia pronta:

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

    Questa sandbox può richiedere più tempo per essere pronta rispetto alla sandbox di origine, perché GKE crea il disco dallo snapshot dopo che quest'ultimo è pronto.

Verifica la persistenza e il ripristino

Verifica che l'agente possa leggere i dati storici.

NEW_POD_NAME=agent-session-v2-restored
kubectl exec ${NEW_POD_NAME} -- cat /workspace/state.txt

Output previsto: Point-in-Time Snapshot - v1

Esegui la pulizia delle risorse

Elimina gli Agent Sandbox, i PVC e il 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 workspace temporaneo

Utilizza il pattern dell'area di lavoro temporanea quando un agente ha bisogno di un volume di archiviazione per archiviare i file temporanei mentre è attivo. Non è necessario conservare dati quando Agent Sandbox viene eliminato.

Configura con avvio in meno di un secondo

Utilizza Agent Sandbox sui pool caldi di GKE per eseguire il pre-provisioning di volumi vuoti in background.

Definisci la risorsa SandboxTemplate

Definisci il backup dello spazio di archiviazione temporaneo all'interno del blocco volumeClaimTemplate.

  1. Salva il seguente manifest come 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
    

Avvia la risorsa SandboxWarmPool

  1. Salva il seguente manifest come 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. Applica entrambi i manifest:

    kubectl apply -f stateless-template.yaml
    kubectl apply -f stateless-warmpool.yaml
    
  3. Attendi che le sandbox del pool caldo siano pronte:

    kubectl wait sandboxwarmpool stateless-warmpool \
        --for=jsonpath='{.status.readyReplicas}'=2 \
        --timeout=600s
    

    Se crei una risorsa SandboxClaim prima che le sandbox del pool siano pronte, il controller potrebbe creare una nuova sandbox per la richiesta anziché assegnarne una dal pool. In un cluster Autopilot, le sandbox possono richiedere diversi minuti per essere pronte perché GKE potrebbe dover creare nodi per loro.

Crea una risorsa SandboxClaim

Definisci una risorsa SandboxClaim che si attiva quando un utente avvia una sessione.

  1. Salva il seguente manifest come stateless-sandbox-claim.yaml:

    apiVersion: extensions.agents.x-k8s.io/v1beta1
    kind: SandboxClaim
    metadata:
      name: agent-1-claim
    spec:
      warmPoolRef:
        name: stateless-warmpool
    
  2. Applica il manifest:

    kubectl apply -f stateless-sandbox-claim.yaml
    

Verifica l'esecuzione in meno di un secondo

Attendi che la richiesta sia pronta, acquisisci il nome del pod Agent Sandbox, quindi verifica che la directory /workspace sia montata e pronta per l'uso immediato:

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

Termina la sessione dell'agente

Per terminare la sessione dell'agente, elimina la risorsa SandboxClaim. L'eliminazione della richiesta comporta anche l'eliminazione della sandbox richiesta e del relativo volume:

kubectl delete sandboxclaim agent-1-claim

Esegui la pulizia delle risorse

Elimina le risorse SandboxWarmPool e SandboxTemplate:

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

Configura con avvio di più secondi

Per implementare un workspace temporaneo che tollera una latenza di più secondi, utilizza la creazione diretta di Agent Sandbox senza un pool caldo.

Definisci un Agent Sandbox stateless

  1. Salva il seguente manifest come 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
    

Esegui il deployment di Agent Sandbox

Per eseguire il provisioning dinamico del disco e collegarlo al nodo pianificato, applica il manifest:

kubectl apply -f sandbox-direct-stateless.yaml

Verifica la latenza di avvio e l'esecuzione

Monitora lo stato del pod per osservare il ritardo di collegamento prima che il pod passi allo stato Running:

kubectl get pods -w

Quando il pod è in esecuzione, premi Ctrl+C per interrompere il monitoraggio.

Acquisisci il nome del pod e verifica che la directory /workspace sia disponibile:

POD_NAME=sandbox-direct-stateless
kubectl exec ${POD_NAME} -- ls -la /workspace

Termina sessione agente

Elimina la risorsa Sandbox per terminare automaticamente il pod e distruggere il relativo spazio di archiviazione temporaneo:

kubectl delete sandbox sandbox-direct-stateless

Passaggi successivi