Kubernetes Agent Sandbox CRD: AI Agent Stateful Terisolasi

Hal pertama yang saya lakukan dengan proyek ini adalah berhenti membaca pengumumannya dan membuka manifest-nya, karena blog Kubernetes dan README repository berbeda pada satu detail yang menentukan apakah perintah install berjalan. Blog menyuruh apply manifest.yaml dari sebuah release, sedangkan README sekarang menyebut sandbox-with-extensions.yaml, dan halaman release v1.0.7 hanya mencantumkan tiga aset: extensions.yaml, sandbox-with-extensions.yaml dan sandbox.yaml.

Tulisan ini adalah pembacaan yang teliti, bukan benchmark yang saya jalankan sendiri. Saya tidak menyiapkan cluster untuk menulisnya. Semua isi berasal dari pengumuman blog Kubernetes tanggal 20 Maret 2026, repository kubernetes-sigs/agent-sandbox (README, threat model, panduan performance tuning, panduan konfigurasi, roadmap, dan contoh manifest) serta halaman PyPI, masing-masing saya ambil pada 17 Oktober 2026. Setiap angka yang muncul adalah angka milik proyeknya, lengkap dengan cluster tempat angka itu diukur.

Mengapa StatefulSet berisi satu pod tidak cukup

Pengumuman itu menggambarkan AI agent sebagai workload singleton yang terisolasi dan stateful: ruang kerja digital bagi sebuah LLM yang membutuhkan identitas persisten dan scratchpad yang aman untuk menulis serta menjalankan kode yang sering kali tidak tepercaya. Karena agent diharapkan lebih banyak diam dan hanya aktif sesekali, mereka juga butuh mekanisme suspend dan resume yang cepat. Para penulisnya, Janet Kuo dan Justin Santa Barbara, mengakui bahwa hal ini bisa didekati dengan StatefulSet berukuran 1, headless Service, dan PersistentVolumeClaim untuk setiap agent, lalu menyebut mengelolanya dalam skala besar sebagai mimpi buruk operasional.

Pembingkaian itulah alasan proyek ini ada, dan itu juga ujian yang saya pakai untuk menilainya. Kalau Anda hanya menjalankan lima agent, resep StatefulSet sudah cukup dan CRD baru hanya menambah beban. CRD baru layak dipakai ketika Anda membuat dan menghapus ribuan sandbox per hari, butuh satu tempat untuk memaksakan RuntimeClass, dan ingin punya pool sandbox yang siap pakai. Pengumumannya sendiri menyebut proyek ini masih dalam pengembangan di bawah SIG Apps.

Empat resource dan satu perintah install yang penting

README mendefinisikan satu resource inti dan tiga ekstensi opt-in. Kind Sandbox berada di agents.x-k8s.io/v1beta1 dan mengelola satu pod stateful dengan hostname, identitas jaringan, dan storage persisten yang stabil. Ekstensinya berada di extensions.agents.x-k8s.io, dan manifest contoh di repository juga memakai v1beta1 untuk ekstensi tersebut. Roadmap menandai perpindahan dari alpha ke beta sebagai selesai: v1beta1 adalah satu-satunya versi yang disajikan, dan tipe v1alpha1 beserta conversion webhook sudah dihapus.

Install cukup dua kali kubectl apply, atau satu kali jika memakai manifest gabungan. Blok di bawah adalah urutan dari README sendiri, diikuti verifikasi yang dianjurkannya. README menyarankan pin versi untuk produksi dan GitOps; v1.0.7, dirilis 15 Oktober 2026, adalah release terbaru saat saya memeriksanya.

# From the README. Pin a version for production and GitOps.
export VERSION="v1.0.7"

# Core + extensions in one manifest (SandboxTemplate, SandboxClaim, SandboxWarmPool):
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$VERSION/sandbox-with-extensions.yaml

# Or split it. Core only, then the opt-in extensions:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$VERSION/sandbox.yaml
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$VERSION/extensions.yaml

# Verify, exactly as the README prescribes:
kubectl get crd sandboxes.agents.x-k8s.io
kubectl get deploy agent-sandbox-controller -n agent-sandbox-system

# The announcement blog (March 2026) still shows the older shape:
#   .../releases/download/vX.Y.Z/manifest.yaml
# v1.0.7 lists sandbox.yaml, extensions.yaml and sandbox-with-extensions.yaml.

# Client SDK (optional):
pip install k8s-agent-sandbox

Isolasi didelegasikan, dan template adalah tempat Anda memaksakannya

Kalimat terpenting dalam threat model juga yang paling mudah terlewat: Agent Sandbox sendiri tidak mengimplementasikan isolasi, tetapi mendukung konfigurasi runtime yang aman. Pengumumannya menyebut resource Sandbox mendukung runtime seperti gVisor atau Kata Containers untuk isolasi kernel dan jaringan. Dalam praktiknya itu adalah mekanisme Kubernetes biasa, yaitu RuntimeClass yang disebut di pod template. Quickstart gVisor milik proyek membuat satu dengan handler runsc dan menyuruh Anda membuka komentar runtimeClassName: gvisor di template.

Threat model lalu menjelaskan di mana isolasi dipaksakan. Administrator platform bisa menetapkan runtimeClassName yang aman di SandboxTemplate yang dipakai SandboxWarmPool, sehingga tenant yang mengklaim sandbox tidak pernah memilih runtime-nya. Itulah keputusan desain yang layak ditiru: letakkan pilihan isolasi di object milik tim platform, bukan di object yang dibuat platform agent untuk setiap sesi.

Di bawah ini adalah template yang saya rakit dari dua file di repository: template klien Python untuk baris runtimeClassName dan resource requests, serta contoh aider untuk network policy dan volume workspace. Ini susunan saya dari field-field mereka, bukan file asli repo, jadi anggap sebagai titik awal dan terapkan dulu ke cluster uji.

# 1. RuntimeClass, as in the project's gVisor quickstart (handler = runsc)
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: gvisor
handler: runsc
---
# 2. Template: the platform team owns this, the claiming tenant never sees it.
#    Fields composed from the Python client template and the aider example.
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxTemplate
metadata:
  name: agent-gvisor
  namespace: default
spec:
  networkPolicyManagement: Managed      # the documented default
  networkPolicy:
    ingress:
    - ports: [{protocol: TCP, port: 8888}]
    egress:
    - ports: [{protocol: UDP, port: 53}, {protocol: TCP, port: 53}]
    - ports: [{protocol: TCP, port: 443}]
  volumeClaimTemplates:
  - metadata:
      name: workspace
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 1Gi
  podTemplate:
    spec:
      runtimeClassName: gvisor          # isolation chosen here, not by the claim
      automountServiceAccountToken: false   # templates default to this when omitted
      restartPolicy: OnFailure
      containers:
      - name: runtime
        image: registry.example.com/agent-runtime:1.0   # replace with your image
        ports:
        - containerPort: 8888
        resources:
          requests: {cpu: 250m, memory: 512Mi, ephemeral-storage: 512Mi}
          limits:   {cpu: "1",  memory: 1Gi,  ephemeral-storage: 1Gi}

Warm pool: apa yang sebenarnya dibeli oleh klaim satu detik itu

Argumen pengumumannya singkat. Menyalakan pod menambah sekitar satu detik overhead, tidak masalah untuk deploy microservice tetapi bermasalah ketika agent yang sedang idle dipanggil dan model harus menunggu sebelum bisa berpikir atau bertindak. SandboxWarmPool menjaga pod sandbox yang sudah disiapkan, dan SandboxClaim menyerahkan salah satunya. Claim contoh di repository hanya mengisi satu field spec: warmPoolRef dengan sebuah name.

# Warm pool: keeps 3 sandboxes ready from the template above.
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxWarmPool
metadata:
  name: agent-gvisor-pool
  namespace: default
spec:
  replicas: 3                  # replicas: 0 means every claim cold-starts
  sandboxTemplateRef:
    name: agent-gvisor         # must match the SandboxTemplate metadata.name
---
# Claim: what your agent platform creates per session.
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxClaim
metadata:
  name: session-4821
  namespace: default
spec:
  warmPoolRef:
    name: agent-gvisor-pool
  # Wrong: setting spec.env or spec.volumeClaimTemplates here disables warm
  # adoption and forces a cold start from the template.

Panduan performance tuning adalah tempat proyek menaruh hasil pengukurannya, dan isinya lebih jujur daripada pengumuman. Panduan itu memisahkan dua rezim dan menyatakannya dengan jelas. Menguras pool yang sudah siap itu murah, tetapi menjaga pool tetap penuh sementara klaim terus datang tidak murah. Tabel ini merangkum angka yang saya baca, lengkap dengan lingkungan asalnya.

Dua catatan dari panduan yang sama mengubah cara Anda memakainya. Pertama, claim yang mengisi spec.env atau spec.volumeClaimTemplates menonaktifkan warm adoption sepenuhnya dan selalu melakukan cold start sandbox baru dari template, karena kustomisasi itu tidak bisa diterapkan ke pod hangat yang sudah berjalan. Kedua, pool dengan spec.replicas bernilai 0 hanya akan cold start dari template-nya. Warm pool yang ukurannya sudah tepat tetapi diklaim dengan env kustom adalah pool yang Anda bayar tetapi tidak pernah terpakai.

Lifecycle stateful: yang sudah ada dan yang baru dijanjikan

Pengumumannya menyebut Agent Sandbox mendukung penskalaan environment idle ke nol sambil memastikan mereka bisa melanjutkan tepat dari posisi terakhir. Roadmap lebih presisi, dan perbedaannya penting jika Anda merencanakan sesuatu di atasnya. Suspend dan resume berbasis PVC tercatat selesai: saat di-scale ke 0, PVC dipertahankan dan dipasang kembali saat resume. Suspend otomatis untuk sandbox yang tidak aktif, dan item Scale to Zero yang terpisah, tercatat sebagai rencana.

Bagian identitas stabil sudah ada dan sederhana: setiap Sandbox mendapat hostname dan identitas jaringan yang stabil sehingga agent yang saling berkoordinasi bisa saling menemukan. Controller menopang setiap Sandbox dengan headless Service yang selector-nya adalah label name-hash, detail yang penting di bagian berikutnya.

Di mana ia menggigit: default keamanan dan jebakan tuning

Threat model-nya luar biasa terus terang tentang apa yang tercakup dan tidak, dan panduan performa mencatat konfigurasi yang gagal, bukan menyembunyikannya. Saya membaca keduanya untuk mencari tempat tim platform bisa terluka. Tabel mencantumkan lima, masing-masing dengan bukti dari kata-kata proyeknya sendiri.

Masalah label spoofing layak punya paragraf sendiri karena itulah jenis bug yang mudah muncul pada CRD seperti ini. Tenant mengendalikan metadata spec.podTemplate, dan Service untuk Sandbox A memilih pod lewat label agents.x-k8s.io/sandbox-name-hash. Jika tenant jahat menyalin nilai label itu ke pod miliknya, traffic untuk Sandbox A bisa sampai ke penyerang. Threat model mendokumentasikan perbaikannya: controller menyaring key di bawah agents.x-k8s.io dan extensions.agents.x-k8s.io dari template pengguna dan menetapkan name-hash setelah menggabungkan label pengguna. Threat model juga mencatat bahwa penguatan hash FNV-1a dilacak secara terpisah.

Satu pergeseran lagi yang perlu diingat: roadmap mencantumkan pemisahan API dari runtime, rolling update untuk template dan warm pool, serta pemilihan warm pool yang lebih cerdas sebagai pekerjaan yang sedang berjalan. Sebuah KEP di repository mengusulkan penyederhanaan SandboxClaim menjadi satu field warmPoolRef. Saya menganggapnya usulan, bukan API yang sudah rilis, tetapi itu mengingatkan agar manifest claim tetap kecil dan dihasilkan dari satu tempat.

Men-tune controller sebelum pool menjadi bottleneck

Panduan konfigurasi punya contoh Deployment untuk throughput tinggi, dan panduan performa menjelaskan tiap flag. Ringkasan yang saya ambil: default aman untuk deployment kecil, dan sebagian besar flag baru berarti ketika Anda menabrak batas konkurensi API server. Pada 75 claim bersamaan, beberapa di antaranya netral. Yang berpengaruh konsisten adalah max refill rate, yang memangkas p50 dan p90 sekitar 15 persen dibanding baseline pada tes GKE, dan rate 80 serta 100 hasilnya sama.

Cuplikan ini hanya menampilkan flag yang saya baca di dua panduan, beserta alasan yang didokumentasikan. Jangan menyalin angkanya sebagai rekomendasi untuk cluster Anda: panduan mengikat angka itu pada profil miliknya sendiri, dan salah satu sapuan jumlah worker menunjukkan terlalu sedikit worker justru memburuk (worker 50, 50, 1, 1 menambah sekitar 11 persen pada p50 dibanding 200, 150, 2, 1).

# Fragment of the agent-sandbox-controller container args.
# Every flag below is named in docs/configuration.md or docs/performance-tuning.md.
# The values are the guides' examples for their own profiles: measure before copying.
args:
- --leader-elect=true
- --extensions=true
# Keep write traffic from starving the watch events that clear a pool's expectations gate.
- --separate-watch-connection=true
- --api-connections=4
# Pace refill as a steady stream instead of 300-sandbox bursts (default rate is 0 = unpaced).
- --sandbox-warm-pool-max-refill-rate=100
- --sandbox-warm-pool-max-batch-size=200
# Parallelism is across distinct SandboxWarmPool objects, not within one pool.
- --sandbox-warm-pool-concurrent-workers=4
# Fewer redundant writes per lifecycle transition.
- --disable-sandbox-events=true
- --disable-claim-events=true
- --disable-claim-observability-annotations=true

# Wrong: --sandbox-warm-pool-replenish-delay=20s. In the GKE test one failed
# claim creation drained the pool and p90 went from 74.2 s to 204.7 s.

Yang dilakukan pada hari Senin

Saya belum akan menaruh ini di depan traffic produksi, dan pengumumannya sendiri menyebut proyek ini masih dalam pengembangan. Namun ia cukup matang untuk dievaluasi di cluster percobaan minggu ini. Urutannya:

1. Install di cluster sekali pakai dengan release yang di-pin, lalu verifikasi CRD dan deployment controller dengan dua perintah dari README.
2. Pastikan isolasi bekerja lebih dulu: buat RuntimeClass gVisor atau Kata, taruh runtimeClassName di SandboxTemplate, dan pastikan pod benar-benar berjalan dengan runtime itu sebelum hal lain.
3. Ukur latensi claim Anda sendiri dengan SandboxWarmPool berisi beberapa replica dibandingkan pool replicas 0 yang dibuat dari template yang sama, sehingga selisih warm dan cold adalah angka dari node Anda sendiri.
4. Uji mode kegagalannya: pod tenant yang mencoba menjangkau 169.254.169.254, pod yang mencoba membaca token service account, dan claim yang mengisi spec.env.
5. Catat bagian lifecycle mana yang harus Anda tangani sendiri (deteksi idle, pembersihan sandbox yang ditinggalkan) karena roadmap mencantumkannya sebagai rencana.

# Does the claimed pod really run under the sandbox runtime?
kubectl get pod -n default -o custom-columns=NAME:.metadata.name,RUNTIME:.spec.runtimeClassName

# Warm versus cold on your own nodes: time a claim against each pool.
time kubectl apply -f claim-warm.yaml
kubectl get sandboxclaim session-4821 -o yaml   # read status.conditions for when it was bound

# Failure probes from inside a sandbox: metadata endpoint and API token.
kubectl exec <sandbox-pod> -- curl -m 3 -s http://169.254.169.254/ ; echo "exit=$?"
kubectl exec <sandbox-pod> -- ls /var/run/secrets/kubernetes.io/serviceaccount

SDK Python tersedia di PyPI sebagai k8s-agent-sandbox, dan SDK Go dirilis dari root module repository. Keduanya adalah sisi klien. Roadmap mencantumkan perluasan SDK Python untuk membaca dan menulis file serta menjalankan perintah sebagai pekerjaan yang sedang berjalan, jadi permukaan itu akan berubah.

Aturan yang saya ambil dari sini: sebuah agent sandbox hanya seaman RuntimeClass di template-nya, dan hanya secepat warm pool yang Anda ukur serta claim yang boleh memakainya. Agent Sandbox menyediakan object untuk menegakkan keduanya di satu tempat, dan dokumentasinya sendiri jujur bahwa beberapa bagian, dari auto-suspend sampai network policy saat claim, masih ada di depan.