Mengelola penyimpanan Sandbox Agen

Dokumen ini memberikan implementasi referensi untuk mengelola penyimpanan untuk Sandbox Agen 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 agent AI.

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

Dokumen ini menerapkan mode akses data Private Isolated Workspace menggunakan akses ReadWriteOnce (RWO). Dalam mode ini, agen dimulai dengan direktori penyimpanan terisolasi pribadi yang hanya dapat diakses baca dan tulis olehnya.

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 di bawah satu detik untuk ruang kerja pemulihan stateful atau point-in-time, Anda harus menggunakan GKE Agent Sandbox Warm Pools. Mengikat penyimpanan ke Pod Kumpulan Siap Pakai yang diklaim memerlukan 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 kompatibel dengan RWX, seperti Filestore Multishares (Enterprise) (enterprise-multishare-rwx).
• Ruang kerja percabangan eksplorasi: pasang folder template sebagai hanya baca dan sediakan papan tulis sementara yang dapat ditulis secara terpisah. 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

Aktifkan Agent Sandbox di cluster Anda.

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 (Sandbox Agen dihapus) dan memulihkan data dari status terbaru saat sesi agen diaktifkan (Sandbox Agen 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 sebelumnya yang berisi data pengguna.

Pola ruang kerja stateful mengikuti urutan peristiwa berikut:

1. Penyediaan: administrator atau orchestrator menyediakan PVC pribadi secara manual untuk setiap sesi agen menggunakan ID deterministik (misalnya, pvc-agent-1).
2. Mereferensikan: 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 melampirkan disk Compute Engine secara dinamis ke VM node, yang menimbulkan penundaan multi-detik standar.
4. Persistensi: saat sesi berakhir (menghapus Sandbox), GKE melepaskan disk, tetapi tidak menghapus PVC, yang membantu memastikan 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 kelas penyimpanan menggunakan binding volume dinamis, disk belum terlampir ke node mana pun. Objek ini akan tetap dalam status Pending hingga Pod yang memintanya dijadwalkan.

Men-deploy Sandbox Agen

Deploy resource kustom Sandbox, dengan 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 melampirkan 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 penurunan skala atau penghentian sesi saat agen tidak aktif, hapus resource Sandbox, tetapi pertahankan penyimpanan yang mendasarinya.

kubectl delete sandbox sandbox-agent-1

GKE akan melepaskan dan memisahkan disk. PVC pvc-agent-1 tetap ada, sehingga data tetap terjaga.

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-boot.

Memverifikasi penyimpanan data

Periksa penampung 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 Sandbox Agen 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, men-debug, atau melakukan pekerjaan independen. Ruang kerja agen diinisialisasi dari set data historis (atau status bersama), menyimpan modifikasi berikutnya ke lapisan yang dapat ditulis terpisah dan pribadi 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 orkestrator untuk menyediakan PersistentVolumeClaim (PVC) baru secara dinamis dari VolumeSnapshot historis sebelum meluncurkan sesi sandbox baru.

Buat 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)

Memicu VolumeSnapshot CSI 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 VolumeSnapshot CSI.

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

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 Sandbox Agen, 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 Sandbox Agen.

Mengonfigurasi dengan startup kurang dari satu detik

Gunakan Kumpulan Siap Pakai Sandbox Agen untuk melakukan pra-penyediaan volume kosong di latar belakang.

Tentukan SandboxTemplate

Tentukan dukungan penyimpanan efemeral 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 Sandbox Warm Pool

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 di bawah satu detik

Ambil nama Pod Agent Sandbox dan verifikasi bahwa direktori /workspace sudah di-mount dan siap digunakan:

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 melepaskan Sandbox yang diklaim, hapus resource SandboxClaim:

kubectl delete sandboxclaim agent-1-claim

Membersihkan resource

Hapus Sandbox Warm Pool dan template Sandbox:

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

Mengonfigurasi dengan startup multi-detik

Untuk menerapkan ruang kerja sementara yang mentoleransi latensi multi-detik, gunakan pembuatan Agent Sandbox langsung tanpa Warm Pool.

Menentukan Sandbox Agen 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 Sandbox Agen

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

kubectl apply -f sandbox-direct-stateless.yaml

Memverifikasi latensi dan eksekusi startup

Pantau status Pod untuk mengamati penundaan lampiran 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 sementara:

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 Sandbox Agen dengan snapshot Pod.