Dokumen ini memberikan implementasi referensi untuk mengelola penyimpanan bagi Agent Sandbox di GKE 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 cara memilih solusi penyimpanan, lihat Memilih penyimpanan untuk workload agentic 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 di GKE dijadwalkan. Untuk membantu memastikan
bahwa GKE menyediakan volume Hyperdisk Balanced untuk
penyimpanan agen, Anda harus menjadwalkan Agent Sandbox di
Pod GKE pada node kelompok mesin yang kompatibel, seperti
N4; jika tidak, GKE akan kembali ke pd-balanced.
Dokumen ini mengimplementasikan mode akses data Private Isolated Workspace menggunakan akses ReadWriteOnce (RWO). Dalam mode ini, agen memulai dengan
direktori penyimpanan pribadi yang terisolasi dan memiliki akses baca dan tulis tunggal.
Kecuali jika ditentukan lain, implementasi referensi dalam dokumen ini menggunakan pembuatan sandbox langsung, yang berlaku untuk agen yang menoleransi latensi startup multi-detik. Untuk mencapai latensi startup di bawah satu detik untuk ruang kerja pemulihan stateful atau point-in-time, Anda harus menggunakan Agent Sandbox di Warm Pool GKE. Mengikat penyimpanan ke Pod Warm Pool yang diklaim memerlukan pembuatan skrip kustom dan DaemonSet dengan 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
accessModesmenjadiReadWriteManydan gunakan StorageClass yang mendukung RWX, seperti Filestore Multishares (Enterprise) (enterprise-multishare-rwx). - Ruang kerja percabangan eksplorasi: memasang folder template sebagai hanya baca
dan menyediakan scratchpad terpisah yang dapat ditulis. Untuk template dasar, Anda
harus menggunakan penyimpanan yang mendukung beberapa lampiran hanya baca, seperti
Hyperdisk ML
dengan mode akses
ReadOnlyMany(ROX) atau Filestore Multishares dengan mode akses RWX.
Sebelum memulai
Pastikan Anda memiliki cluster GKE yang telah menginstal pengontrol Agent Sandbox. Jika belum, selesaikan hanya bagian berikut dari Menginstal Agent Sandbox di GKE, lalu kembali ke dokumen ini:
- Menentukan variabel lingkungan
- Membuat cluster GKE
- Menginstal Agent Sandbox
- Menerapkan kebijakan keamanan yang direkomendasikan
Jika Anda telah menyelesaikan bagian Men-deploy lingkungan dengan sandbox dalam dokumen tersebut, hapus resource contoh yang dibuatnya agar node Anda memiliki kapasitas yang cukup untuk sandbox dalam dokumen ini:
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
Mengonfigurasi ruang kerja stateful
Gunakan pola ini untuk mempertahankan status terbaru file agen. Hal 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 menoleransi 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:
- Penyediaan: administrator atau orchestrator menyediakan PVC pribadi secara manual untuk setiap sesi agen menggunakan ID deterministik (misalnya,
pvc-agent-1). - Mereferensikan: di resource
Sandbox, Anda menggunakan kolompersistentVolumeClaimdalam blokvolumesuntuk menentukanclaimNameyang tepat dari volume yang ada. - Latensi: saat sandbox dibuat, GKE harus melampirkan disk Compute Engine secara dinamis ke VM node, yang menimbulkan penundaan standar selama beberapa detik.
- Persistensi: saat penghentian sesi (menghapus resource
Sandbox), GKE melepaskan disk, tetapi tidak menghancurkan PVC, yang membantu memastikan bahwa status terbaru dipertahankan untuk sesi berikutnya.
Untuk mengonfigurasi ruang kerja stateful yang mempertahankan data di antara sesi, selesaikan langkah-langkah di subbagian berikut.
Menyediakan ruang kerja persisten (PVC)
Buat PersistentVolumeClaim (PVC) pribadi yang menggunakan ID deterministik, seperti pvc-agent-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: 10GiTerapkan manifes:
kubectl apply -f pvc-agent-1.yaml
Karena kelas penyimpanan menggunakan binding volume dinamis, disk belum terpasang ke node mana pun. Volume tetap dalam status Pending hingga Pod yang memintanya dijadwalkan.
Men-deploy Agent Sandbox
Deploy resource kustom Sandbox, yang mereferensikan PVC deterministik.
Simpan manifes berikut sebagai
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: OnFailureTerapkan manifes:
kubectl apply -f sandbox-agent-1.yamlTunggu hingga sandbox siap:
kubectl wait sandbox sandbox-agent-1 \ --for=condition=Ready \ --timeout=300sGKE memverifikasi kapasitas node dan memasang disk, yang memerlukan waktu beberapa detik. Container melakukan inisialisasi di dalam kernel gVisor userspace. Dalam cluster Autopilot, sandbox mungkin memerlukan waktu beberapa menit untuk siap karena GKE mungkin perlu membuat node untuk sandbox tersebut.
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 perkecil skala atau penghentian sesi saat agen tidak ada aktivitas, hapus resource Sandbox, tetapi pertahankan penyimpanan yang mendasarinya.
kubectl delete sandbox sandbox-agent-1
GKE akan melepas dan mencopot disk. PVC pvc-agent-1 tetap ada, sehingga data tetap tersimpan.
Mengaktifkan kembali sesi agen
Untuk mengaktifkan kembali sesi, deploy ulang resource Sandbox baru yang mereferensikan
PVC yang sama, lalu tunggu hingga sandbox siap:
kubectl apply -f sandbox-agent-1.yaml
kubectl wait sandbox sandbox-agent-1 \
--for=condition=Ready \
--timeout=300s
Disk dipasang kembali (menimbulkan penundaan pemasangan), dan container melakukan booting.
Memverifikasi pelestarian 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 ${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 terpisah yang dapat ditulis secara pribadi tanpa mengubah template dasar.
Implementasi referensi di bagian ini menggunakan pembuatan sandbox langsung dan berlaku untuk agen yang menoleransi latensi startup multi-detik. Pendekatan ini mengandalkan orchestrator 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.
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: DeleteTerapkan manifes:
kubectl apply -f 1-snapshot-class.yaml
Menyediakan ruang kerja awal
Buat volume tempat agen akan melakukan pekerjaan awalnya.
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: 10GiTerapkan manifes:
kubectl apply -f 2-source-pvc.yaml
Membuat data status
Men-deploy Pod sandbox untuk menulis data ke volume.
Simpan manifes berikut sebagai
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: OnFailureTerapkan manifes:
kubectl apply -f 3-source-sandbox.yamlTunggu hingga sandbox siap, lalu tulis state file. Perintah
syncakan menghapus penulisan ke disk sehingga snapshot di bagian berikutnya menyertakan konten 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"
Mengarsipkan status historis (VolumeSnapshot CSI)
Memicu VolumeSnapshot CSI untuk membekukan status saat ini. Saat mengambil snapshot, ikuti praktik terbaik untuk snapshot disk.
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-pvcTerapkan manifes:
kubectl apply -f 4-volume-snapshot.yamlTunggu hingga snapshot siap digunakan:
kubectl wait volumesnapshot agent-session-v1-snapshot \ --for=jsonpath='{.status.readyToUse}'=true \ --timeout=600s
Memulihkan volume dari snapshot
Deploy PVC baru dengan dataSource yang mengarah ke VolumeSnapshot CSI.
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: 10GiTerapkan manifes:
kubectl apply -f 5-restored-pvc.yaml
Meluncurkan sesi Agent Sandbox yang dipulihkan
Sediakan resource Sandbox baru yang mereferensikan PVC yang baru dipulihkan.
Simpan manifes berikut sebagai
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: OnFailureTerapkan manifes:
kubectl apply -f 6-restored-sandbox.yamlTunggu hingga sandbox siap:
kubectl wait sandbox agent-session-v2-restored \ --for=condition=Ready \ --timeout=600sSandbox ini memerlukan waktu lebih lama untuk siap dibandingkan sandbox sumber karena GKE membuat disk-nya dari snapshot setelah snapshot siap.
Memverifikasi persistensi dan pemulihan
Pastikan 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 penghapusan Agent Sandbox.
Mengonfigurasi dengan startup sub-detik
Gunakan Agent Sandbox di Warm Pool GKE untuk melakukan pra-penyediaan volume kosong di latar belakang.
Menentukan resource SandboxTemplate
Tentukan dukungan penyimpanan efemeral dalam blok volumeClaimTemplate.
Simpan manifes berikut sebagai
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
Meluncurkan resource SandboxWarmPool
Simpan manifes berikut sebagai
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-templateTerapkan kedua manifes:
kubectl apply -f stateless-template.yaml kubectl apply -f stateless-warmpool.yamlTunggu hingga sandbox warm pool siap:
kubectl wait sandboxwarmpool stateless-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sJika Anda membuat resource
SandboxClaimsebelum sandbox pool siap, pengontrol mungkin akan membuat sandbox baru untuk klaim, bukan menetapkan sandbox dari pool. Dalam cluster Autopilot, sandbox dapat memerlukan waktu beberapa menit untuk siap karena GKE mungkin perlu membuat node untuk sandbox tersebut.
Membuat resource SandboxClaim
Tentukan resource SandboxClaim yang dipicu saat pengguna memulai sesi.
Simpan manifes berikut sebagai
stateless-sandbox-claim.yaml:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxClaim metadata: name: agent-1-claim spec: warmPoolRef: name: stateless-warmpoolTerapkan manifes:
kubectl apply -f stateless-sandbox-claim.yaml
Memverifikasi eksekusi sub-detik
Tunggu hingga klaim siap, ambil nama Pod Agent Sandbox, lalu
verifikasi bahwa direktori /workspace telah terpasang dan siap digunakan:
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
Menghentikan sesi agen
Untuk mengakhiri sesi agen, hapus resource SandboxClaim. Menghapus klaim juga akan menghapus sandbox yang diklaim dan volumenya:
kubectl delete sandboxclaim agent-1-claim
Membersihkan resource
Hapus resource SandboxWarmPool dan SandboxTemplate:
kubectl delete sandboxwarmpool stateless-warmpool
kubectl delete sandboxtemplate stateless-sandbox-template
Mengonfigurasi dengan startup multi-detik
Untuk menerapkan ruang kerja sementara yang menoleransi latensi beberapa detik, gunakan pembuatan Agent Sandbox langsung tanpa Warm Pool.
Menentukan Agent Sandbox stateless
Simpan manifes berikut sebagai
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
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
Saat Pod berjalan, tekan Control+C untuk berhenti melihat.
Ambil nama Pod dan pastikan 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 efemeralnya:
kubectl delete sandbox sandbox-direct-stateless
Langkah berikutnya
- Pelajari lebih lanjut Agent Sandbox di GKE.
- Pelajari lebih lanjut cara mengisolasi eksekusi kode AI dengan Agent Sandbox di GKE.
- Pelajari cara Menyimpan dan memulihkan Agent Sandbox di lingkungan GKE dengan snapshot Pod.