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:
- Configura uno spazio di lavoro stateful
- Configura un ripristino a un punto specifico nel tempo e il trasferimento di proprietà
- Configura una workstation temporanea
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
accessModesinReadWriteManye 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:
- Definisci le variabili di ambiente
- Crea un cluster GKE
- Installa Agent Sandbox
- 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:
- 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). - Riferimento: nella risorsa
Sandbox, utilizzi il campopersistentVolumeClaimall'interno del bloccovolumesper specificare l'esattoclaimNamedel volume esistente. - 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.
- 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.
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: 10GiApplica 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.
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: OnFailureApplica il manifest:
kubectl apply -f sandbox-agent-1.yamlAttendi che la sandbox sia pronta:
kubectl wait sandbox sandbox-agent-1 \ --for=condition=Ready \ --timeout=300sGKE 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.
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: DeleteApplica 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.
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: 10GiApplica 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.
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: OnFailureApplica il manifest:
kubectl apply -f 3-source-sandbox.yamlAttendi che la sandbox sia pronta, quindi scrivi un file di stato. Il comando
syncforza 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.
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-pvcApplica il manifest:
kubectl apply -f 4-volume-snapshot.yamlAttendi 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.
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: 10GiApplica 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.
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: OnFailureApplica il manifest:
kubectl apply -f 6-restored-sandbox.yamlAttendi che la sandbox sia pronta:
kubectl wait sandbox agent-session-v2-restored \ --for=condition=Ready \ --timeout=600sQuesta 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.
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
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-templateApplica entrambi i manifest:
kubectl apply -f stateless-template.yaml kubectl apply -f stateless-warmpool.yamlAttendi che le sandbox del pool caldo siano pronte:
kubectl wait sandboxwarmpool stateless-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sSe crei una risorsa
SandboxClaimprima 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.
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-warmpoolApplica 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
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
- Scopri di più su Agent Sandbox su GKE.
- Scopri di più sull'isolamento dell'esecuzione di codice AI con Agent Sandbox su GKE.
- Scopri come salvare e ripristinare Agent Sandbox negli ambienti GKE con gli snapshot dei pod.