Mengelola penyimpanan Agent Sandbox di GKE

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:

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 accessModes menjadi ReadWriteMany dan 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:

  1. Menentukan variabel lingkungan
  2. Membuat cluster GKE
  3. Menginstal Agent Sandbox
  4. 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:

  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 standar selama beberapa detik.
  4. 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.

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

  1. 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: OnFailure
    
  2. Terapkan manifes:

    kubectl apply -f sandbox-agent-1.yaml
    
  3. Tunggu hingga sandbox siap:

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

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

  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

Men-deploy Pod sandbox untuk menulis data ke volume.

  1. 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: OnFailure
    
  2. Terapkan manifes:

    kubectl apply -f 3-source-sandbox.yaml
    
  3. Tunggu hingga sandbox siap, lalu tulis state file. Perintah sync akan 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.

  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
    
  3. Tunggu 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.

  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/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. Terapkan manifes:

    kubectl apply -f 6-restored-sandbox.yaml
    
  3. Tunggu hingga sandbox siap:

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

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

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

  1. 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-template
    
  2. Terapkan kedua manifes:

    kubectl apply -f stateless-template.yaml
    kubectl apply -f stateless-warmpool.yaml
    
  3. Tunggu hingga sandbox warm pool siap:

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

    Jika Anda membuat resource SandboxClaim sebelum 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.

  1. 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-warmpool
    
  2. Terapkan 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

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