Mengelola penyimpanan Sandbox Agen

Autopilot Standard

Dokumen ini menyediakan implementasi referensi untuk mengelola penyimpanan Agent Sandbox yang disesuaikan dengan kebutuhan siklus proses data agen Anda.

Bergantung pada kebutuhan siklus proses data agen Anda, pilih salah satu konfigurasi berikut:

• Mengonfigurasi ruang kerja stateful
• Mengonfigurasi pemulihan point-in-time dan transfer kepemilikan
• Mengonfigurasi ruang kerja sementara

Untuk mengetahui informasi selengkapnya tentang memilih solusi penyimpanan, lihat Memilih penyimpanan untuk workload agen AI.

Dokumen berikut menggunakan StorageClass dynamic-rwo untuk pemilihan jenis disk otomatis guna menyediakan disk yang kompatibel dengan jenis mesin node tempat Pod Agent Sandbox dijadwalkan. Untuk membantu memastikan GKE menyediakan volume Hyperdisk Balanced untuk penyimpanan agen Anda, Anda harus menjadwalkan Agent Sandbox di node keluarga mesin yang kompatibel, seperti N4. Jika tidak, GKE akan kembali ke pd-balanced.

Dokumen ini mengimplementasikan mode akses data Ruang Kerja Terisolasi Pribadi menggunakan akses ReadWriteOnce (RWO). Dalam mode ini, agen dimulai dengan direktori penyimpanan terisolasi pribadi yang memiliki akses baca dan tulis eksklusif.

Kecuali jika ditentukan lain, implementasi referensi dalam dokumen ini menggunakan pembuatan sandbox langsung, yang berlaku untuk agen yang mentoleransi latensi startup multi-detik. Untuk mencapai latensi startup sub-detik untuk ruang kerja stateful atau pemulihan point-in-time, Anda harus menggunakan Kumpulan Hangat GKE Agent Sandbox. Mengikat penyimpanan ke Pod Kumpulan Hangat yang diklaim memerlukan pembuatan skrip kustom dan DaemonSet yang memiliki hak istimewa. Untuk implementasi referensi, lihat contoh GitHub ini.

Mode akses alternatif

Untuk mendukung mode akses alternatif, Anda dapat mengubah definisi volume dan snapshot dalam konfigurasi:

• Ruang kerja kolaboratif: ubah accessModes menjadi ReadWriteMany dan gunakan StorageClass yang mendukung RWX, seperti Filestore Multishares (Enterprise) (enterprise-multishare-rwx).
• Ruang kerja percabangan eksplorasi: pasang folder template sebagai hanya baca dan sediakan scratchpad yang dapat ditulis secara terpisah. Untuk template dasar, Anda harus menggunakan penyimpanan yang mendukung beberapa lampiran hanya baca, seperti Hyperdisk ML dengan ReadOnlyMany (ROX) mode akses atau Filestore Multishares dengan mode akses RWX.

Sebelum memulai

Aktifkan Agent Sandbox di cluster Anda.

Mengonfigurasi ruang kerja stateful

Gunakan pola ini untuk mempertahankan status terbaru file agen. Pola ini berguna saat agen Anda harus mempertahankan status saat sesi agen dijeda atau dihentikan (Agent Sandbox dihapus) dan memulihkan data dari status terbaru saat sesi agen diaktifkan (Agent Sandbox dibuat ulang).

Implementasi referensi di bagian ini menggunakan pembuatan sandbox langsung dan berlaku untuk agen yang mentoleransi latensi startup multi-detik.

Pendekatan ini menggunakan resource PersistentVolumeClaim (PVC) GKE standar untuk menautkan sandbox ke PVC yang sudah ada yang berisi data pengguna.

Pola ruang kerja stateful mengikuti urutan peristiwa berikut:

1. Penyediaan: administrator atau pengatur menyediakan PVC pribadi secara manual untuk setiap sesi agen menggunakan ID deterministik (misalnya, pvc-agent-1).
2. Referensi: di resource Sandbox, Anda menggunakan kolom persistentVolumeClaim dalam blok volumes untuk menentukan claimName yang tepat dari volume yang ada.
3. Latensi: saat sandbox dibuat, GKE harus memasang disk Compute Engine secara dinamis ke VM node, yang akan menimbulkan penundaan multi-detik standar.
4. Persistensi: saat sesi dihentikan (menghapus Sandbox), GKE akan melepaskan disk, tetapi tidak menghancurkan PVC, yang membantu memastikan bahwa status terbaru dipertahankan untuk sesi berikutnya.

Untuk mengonfigurasi ruang kerja stateful yang mempertahankan data antar-sesi, selesaikan langkah-langkah di subbagian berikut.

Menyediakan ruang kerja persisten (PVC)

Buat PersistentVolumeClaim (PVC) pribadi yang menggunakan ID deterministik, seperti pvc-agent-1.

1. Simpan manifes berikut sebagai 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. Terapkan manifes:

   kubectl apply -f pvc-agent-1.yaml
   

Karena class penyimpanan menggunakan binding volume dinamis, disk belum terpasang ke node mana pun. Disk akan tetap dalam status Pending hingga Pod yang memintanya dijadwalkan.

Men-deploy Agent Sandbox

Deploy resource kustom Sandbox, yang mereferensikan PVC deterministik.

1. Simpan manifes berikut sebagai 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. Terapkan manifes:

   kubectl apply -f sandbox-agent-1.yaml
   

GKE memverifikasi kapasitas node dan memasang disk, yang memerlukan waktu beberapa detik. Container diinisialisasi di dalam kernel gVisor ruang pengguna.

Menulis data dari agen

Simulasikan agen AI aktif yang menjalankan modifikasi file di dalam ruang kerjanya dengan menulis file teks ke disk yang terpasang.

# 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

Mengakhiri sesi agen

Untuk menyimulasikan penskalaan atau menghentikan sesi saat agen tidak aktif, hapus resource Sandbox, tetapi pertahankan penyimpanan yang mendasarinya.

kubectl delete sandbox sandbox-agent-1

GKE melepaskan dan menghapus disk. PVC pvc-agent-1 tetap ada, sehingga data dipertahankan.

Mengaktifkan kembali sesi agen

Untuk mengaktifkan kembali sesi, deploy ulang resource Sandbox baru yang mereferensikan PVC yang sama.

kubectl apply -f sandbox-agent-1.yaml

Disk dipasang kembali (menimbulkan penundaan pemasangan), dan container di-booting.

Memverifikasi penyimpanan data

Periksa container sandbox yang baru dibuat untuk memverifikasi bahwa data sesi sebelumnya dipertahankan.

# 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

Output akan menampilkan Workspace State Saved - Agent 1.

Membersihkan resource

Hapus Agent Sandbox dan klaim volume persisten terkait:

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

Mengonfigurasi pemulihan point-in-time dan transfer kepemilikan

Gunakan pola ini untuk meng-clone set data guna menjalankan eksperimen paralel, proses debug, atau pekerjaan independen. Ruang kerja agen diinisialisasi dari set data historis (atau status bersama), yang menyimpan modifikasi berikutnya ke lapisan yang dapat ditulis pribadi dan terpisah tanpa mengubah template dasar.

Implementasi referensi di bagian ini menggunakan pembuatan sandbox langsung dan berlaku untuk agen yang mentoleransi latensi startup multi-detik. Pendekatan ini mengandalkan pengatur untuk menyediakan PersistentVolumeClaim (PVC) baru secara dinamis dari VolumeSnapshot historis sebelum meluncurkan sesi sandbox baru.

Membuat VolumeSnapshotClass

Buat VolumeSnapshotClass yang menentukan driver CSI dan kebijakan penghapusan. Untuk Hyperdisk, gunakan driver pd.csi.storage.gke.io.

1. Simpan manifes berikut sebagai 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. Terapkan manifes:

   kubectl apply -f 1-snapshot-class.yaml
   

Menyediakan ruang kerja awal

Buat volume tempat agen akan melakukan pekerjaan awalnya.

1. Simpan manifes berikut sebagai 2-source-pvc.yaml:

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

2. Terapkan manifes:

   kubectl apply -f 2-source-pvc.yaml
   

Membuat data status

Deploy Pod sandbox untuk menulis data ke volume.

1. Simpan manifes berikut sebagai 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. Terapkan manifes:

   kubectl apply -f 3-source-sandbox.yaml
   

3. Tunggu hingga Pod berjalan, lalu tulis file status:

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

Mengarsipkan status historis (CSI VolumeSnapshot)

Picu CSI VolumeSnapshot untuk membekukan status saat ini. Saat mengambil snapshot, ikuti praktik terbaik untuk snapshot disk.

1. Simpan manifes berikut sebagai 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. Terapkan manifes:

   kubectl apply -f 4-volume-snapshot.yaml
   

Memulihkan volume dari snapshot

Deploy PVC baru dengan dataSource yang mengarah ke CSI VolumeSnapshot.

1. Simpan manifes berikut sebagai 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. Terapkan manifes:

   kubectl apply -f 5-restored-pvc.yaml
   

Meluncurkan sesi Agent Sandbox yang dipulihkan

Sediakan resource Sandbox baru yang mereferensikan PVC yang baru dipulihkan.

1. Simpan manifes berikut sebagai 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. Terapkan manifes:

   kubectl apply -f 6-restored-sandbox.yaml
   

Memverifikasi persistensi dan pemulihan

Verifikasi bahwa agen dapat membaca data historis.

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

Output yang Diharapkan: Point-in-Time Snapshot - v1

Membersihkan resource

Hapus Agent Sandbox, PVC, dan 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

Mengonfigurasi ruang kerja sementara

Gunakan pola ruang kerja sementara saat agen memerlukan volume penyimpanan untuk menyimpan file sementara saat agen aktif. Tidak ada data yang perlu dipertahankan saat Agent Sandbox dihapus.

Mengonfigurasi dengan startup sub-detik

Gunakan Kumpulan Hangat Agent Sandbox untuk menyediakan volume kosong di latar belakang.

Menentukan SandboxTemplate

Tentukan dukungan penyimpanan sementara dalam blok volumeClaimTemplate.

1. Simpan manifes berikut sebagai 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
   

Meluncurkan Kumpulan Hangat Sandbox

1. Simpan manifes berikut sebagai 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. Terapkan kedua manifes:

   kubectl apply -f stateless-template.yaml
   kubectl apply -f stateless-warmpool.yaml
   

Mengklaim Sandbox

Tentukan SandboxClaim yang dipicu saat pengguna memulai sesi.

1. Simpan manifes berikut sebagai 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. Terapkan manifes:

   kubectl apply -f stateless-sandbox-claim.yaml
   

Memverifikasi eksekusi sub-detik

Ambil nama Pod Agent Sandbox dan verifikasi bahwa direktori /workspace terpasang dan siap digunakan segera:

export POD_NAME=$(kubectl get sandboxclaim agent-1-claim -o jsonpath='{.status.sandbox.name}')
kubectl exec $POD_NAME -- ls -la /workspace

Menghentikan sesi agen

Untuk mengakhiri sesi agen dan merilis Sandbox yang diklaim, hapus resource SandboxClaim:

kubectl delete sandboxclaim agent-1-claim

Membersihkan resource

Hapus Kumpulan Hangat Sandbox dan template Sandbox:

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

Mengonfigurasi dengan startup multi-detik

Untuk mengimplementasikan ruang kerja sementara yang mentoleransi latensi multi-detik, gunakan pembuatan Agent Sandbox langsung tanpa Kumpulan Hangat.

Menentukan Agent Sandbox stateless

1. Simpan manifes berikut sebagai 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
   

Men-deploy Agent Sandbox

Untuk menyediakan disk secara dinamis dan memasangnya ke node terjadwal, terapkan manifes:

kubectl apply -f sandbox-direct-stateless.yaml

Memverifikasi latensi dan eksekusi startup

Pantau status Pod untuk mengamati penundaan pemasangan sebelum Pod bertransisi ke status Running:

kubectl get pods -w

Setelah Pod berjalan, ambil nama Pod dan verifikasi bahwa direktori /workspace tersedia:

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

Menghentikan sesi agen

Hapus resource Sandbox untuk menghentikan Pod secara otomatis dan menghancurkan penyimpanan sementaranya:

kubectl delete sandbox sandbox-direct-stateless

Langkah berikutnya

• Pelajari lebih lanjut GKE Agent Sandbox.
• Pelajari lebih lanjut cara mengisolasi eksekusi kode AI dengan Agent Sandbox.
• Pelajari cara Menyimpan dan memulihkan lingkungan Agent Sandbox dengan snapshot Pod.