Mengisolasi eksekusi kode AI dengan Sandbox Agen

Dokumen ini memberikan petunjuk untuk menginstal dan menjalankan pengontrol Sandbox Agen di cluster Google Kubernetes Engine (GKE). Dokumen ini juga menjelaskan cara men-deploy lingkungan dalam sandbox di cluster tempat Anda dapat menguji perintah shell yang tidak tepercaya.

Pengontrol Sandbox Agen menyediakan framework untuk membuat dan mengelola lingkungan runtime sementara. Pendekatan ini memungkinkan Anda menentukan template untuk lingkungan aplikasi, lalu membuat instance sesuai permintaan.

Sandbox Agen menyediakan lingkungan yang aman dan terisolasi untuk mengeksekusi kode yang tidak tepercaya, seperti kode yang dihasilkan oleh model bahasa besar (LLM). Menjalankan jenis kode ini secara langsung di cluster menimbulkan risiko keamanan, karena kode yang tidak tepercaya berpotensi mengakses atau mengganggu aplikasi lain atau node cluster yang mendasarinya.

Sandbox Agen mengurangi risiko ini dengan menyediakan isolasi proses, penyimpanan, dan jaringan yang kuat untuk kode yang dijalankannya. Isolasi ini dicapai menggunakan gVisor, teknologi yang menciptakan penghalang aman antara aplikasi dan sistem operasi node cluster. Teknologi sandboxing lainnya, misalnya container Kata, dapat digunakan sebagai gantinya; namun, contoh dalam dokumen ini hanya menggunakan gVisor.

Dokumen ini memberikan petunjuk untuk menjalankan Agent Sandbox di cluster GKE Autopilot atau cluster Standard.

Agent Sandbox adalah project open source. Untuk mengetahui informasi selengkapnya tentang cara berkontribusi pada project atau menemukan detail teknis yang lebih mendalam, lihat project open source Agent Sandbox.

Biaya

Mengikuti langkah-langkah dalam dokumen ini akan menimbulkan biaya pada akun Anda. Google CloudBiaya dimulai saat Anda membuat cluster GKE. Biaya ini mencakup biaya per cluster untuk GKE, seperti yang diuraikan di halaman Harga, dan biaya untuk menjalankan VM Compute Engine.

Untuk menghindari tagihan yang tidak perlu, pastikan Anda menonaktifkan GKE atau menghapus project setelah menyelesaikan dokumen ini.

Sebelum memulai

  1. Di konsol Google Cloud , pada halaman pemilih project, pilih atau buat project Google Cloud .

    Peran yang diperlukan untuk memilih atau membuat project

    • Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
    • Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

    Buka pemilih project

  2. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

  3. Aktifkan Artifact Registry, Google Kubernetes Engine API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Aktifkan API

  4. Di konsol Google Cloud , aktifkan Cloud Shell.

    Aktifkan Cloud Shell

Menentukan variabel lingkungan

Untuk menyederhanakan perintah yang Anda jalankan dalam dokumen ini, Anda dapat menetapkan variabel lingkungan di Cloud Shell. Di Cloud Shell, tentukan variabel lingkungan berguna berikut dengan menjalankan perintah berikut:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"

Berikut penjelasan variabel lingkungan ini:

  • PROJECT_ID: ID Google Cloud project Anda saat ini. Menentukan variabel ini membantu memastikan bahwa semua resource, seperti cluster GKE, dibuat di project yang benar.
  • CLUSTER_NAME: nama cluster GKE Anda—misalnya, agent-sandbox-cluster.
  • GKE_LOCATION: Google Cloud region tempat cluster GKE dan repositori Artifact Registry Anda akan dibuat—misalnya, us-central1. Sebaiknya letakkan secara bersamaan karena hal ini mengurangi latensi penarikan gambar.
  • AGENT_SANDBOX_VERSION: versi pengontrol Agent Sandbox yang akan di-deploy ke cluster Anda.
  • NODE_POOL_NAME: nama node pool yang akan menjalankan beban kerja sandbox—misalnya, agent-sandbox-node-pool.
  • MACHINE_TYPE: jenis mesin node di node pool Anda—misalnya, e2-standard-2. Untuk mengetahui detail tentang berbagai seri mesin dan cara memilih di antara berbagai opsi, lihat Panduan perbandingan dan resource kelompok mesin.

Men-deploy Sandbox Agen

Setelah menyiapkan project dan lingkungan Cloud Shell, Anda siap menyediakan infrastruktur yang diperlukan dan men-deploy Sandbox Agen. Google Cloud

Membuat cluster GKE

Selanjutnya, Anda membuat cluster GKE yang mengaktifkan gVisor. Cluster ini menyediakan lingkungan Kubernetes tempat Anda akan men-deploy dan menjalankan pengontrol Agent Sandbox dan aplikasi dalam sandbox contoh. gVisor menyediakan teknologi sandbox untuk menjalankan kode yang tidak tepercaya secara aman.

Anda dapat membuat cluster Autopilot atau Standard. Autopilot mengaktifkan gVisor secara otomatis, sedangkan cluster Standard mengharuskan Anda membuat node pool yang mendukung gVisor secara manual:

Autopilot

Untuk membuat cluster Autopilot menggunakan gcloud CLI, jalankan perintah berikut:

gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}

Standar

Untuk membuat cluster Standar menggunakan gcloud CLI, lakukan langkah-langkah berikut:

  1. Membuat cluster:

    gcloud container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

  2. Buat node pool terpisah dengan gVisor yang diaktifkan:

    gcloud container node-pools create ${NODE_POOL_NAME} \
  --cluster=${CLUSTER_NAME} \
  --location=${GKE_LOCATION} \
  --machine-type=${MACHINE_TYPE} \
  --image-type=cos_containerd \
  --sandbox type=gvisor

Ambil kredensial cluster agar CLI kubectl dapat terhubung ke cluster. Perintah ini memperbarui file konfigurasi Kubernetes Anda, yang disimpan secara default di direktori ~/.kube/config. File konfigurasi ini berisi kredensial yang diperlukan kubectl untuk berinteraksi dengan cluster GKE Anda:

gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

Men-deploy pengontrol Agent Sandbox ke cluster Anda

Anda dapat men-deploy pengontrol Agent Sandbox dan komponen yang diperlukan dengan menerapkan manifes rilis resmi ke cluster Anda. Manifes ini adalah file konfigurasi yang menginstruksikan Kubernetes untuk mendownload semua komponen yang diperlukan untuk men-deploy dan menjalankan pengontrol Sandbox Agen di cluster Anda.

Jalankan perintah berikut untuk men-deploy pengontrol Agent Sandbox ke cluster GKE Anda:

kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml

Memverifikasi pengontrol Sandbox Agen

Setelah Anda menerapkan manifes, periksa apakah Pod pengontrol Agent Sandbox berjalan dengan benar di namespace agent-sandbox-system:

kubectl get pods -n agent-sandbox-system

Tunggu hingga Pod menampilkan 'Running' di kolom STATUS dan '1/1' di kolom READY. Jika Pod berjalan dengan benar, output-nya akan terlihat mirip dengan ini:

NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0   1/1     Running   0          44d

Sekarang setelah pengontrol Agent Sandbox berjalan, pengontrol tersebut dapat membuat dan mengelola lingkungan sandbox secara otomatis untuk resource Sandbox apa pun yang Anda buat di cluster.

Men-deploy lingkungan dalam sandbox

Setelah pengontrol Agent Sandbox berjalan di cluster GKE, Anda perlu men-deploy komponen untuk lingkungan sandbox contoh. Bagian ini menunjukkan cara membuat cetak biru sandbox (SandboxTemplate), men-deploy router jaringan yang diperlukan, dan menginstal klien Python yang akan Anda gunakan untuk berinteraksi dengan sandbox.

Cara yang direkomendasikan untuk membuat dan berinteraksi dengan sandbox Anda adalah dengan menggunakan klien Python Agentic Sandbox. Klien ini menyediakan antarmuka yang menyederhanakan seluruh siklus proses sandbox, mulai dari pembuatan hingga pembersihan. Ini adalah library Python yang dapat Anda gunakan untuk membuat, menggunakan, dan menghapus sandbox secara terprogram.

Klien menggunakan Sandbox Router sebagai titik entri pusat untuk semua traffic. Dalam contoh yang dijelaskan dalam dokumen ini, klien membuat tunnel ke router ini menggunakan perintah kubectl port-forward, sehingga Anda tidak perlu mengekspos alamat IP publik. Perhatikan bahwa penggunaan kubectl port-forward bukanlah solusi yang aman dan penggunaannya harus dibatasi untuk lingkungan pengembangan.

Buat SandboxTemplate dan SandboxWarmPool

Sekarang Anda menentukan konfigurasi untuk sandbox dengan membuat SandboxTemplate dan resource SandboxWarmPool. SandboxTemplate bertindak sebagai cetak biru yang dapat digunakan kembali yang digunakan pengontrol Agent Sandbox untuk membuat lingkungan sandbox yang konsisten dan telah dikonfigurasi sebelumnya. Resource SandboxWarmPool memastikan bahwa sejumlah Pod yang telah disiapkan selalu berjalan dan siap untuk diklaim. Sandbox yang sudah dipanaskan adalah Pod yang sedang berjalan dan sudah diinisialisasi. Pra-inisialisasi ini memungkinkan sandbox baru dibuat dalam waktu kurang dari satu detik, dan menghindari latensi startup saat meluncurkan sandbox biasa:

  1. Di Cloud Shell, buat file bernama sandbox-template-and-pool.yaml dengan konten berikut:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      containers:
      - name: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
            ephemeral-storage: "512Mi"
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template

  2. Terapkan manifes SandboxTemplate dan SandboxWarmPool:

    kubectl apply -f sandbox-template-and-pool.yaml

Men-deploy Sandbox Router

Klien Python yang akan Anda gunakan untuk membuat dan berinteraksi dengan lingkungan sandbox menggunakan komponen yang disebut Sandbox Router untuk berkomunikasi dengan sandbox.

Untuk contoh ini, Anda menggunakan mode developer klien untuk pengujian. Mode ini ditujukan untuk pengembangan lokal, dan menggunakan perintah kubectl port-forward untuk membuat tunnel langsung dari komputer lokal Anda ke layanan Sandbox Router yang berjalan di cluster. Pendekatan tunneling ini menghindari kebutuhan akan alamat IP publik atau penyiapan ingress yang rumit, dan menyederhanakan interaksi dengan sandbox dari lingkungan lokal Anda.

Ikuti langkah-langkah berikut untuk men-deploy Sandbox Router:

  1. Di Cloud Shell, buat file bernama sandbox-router.yaml dengan konten berikut:

    # A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 2 # Run at least two replicas for high availability
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:v20251124-v0.1.0-10-ge26ddb2
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

  2. Terapkan manifes untuk men-deploy router ke cluster Anda:

    kubectl apply -f sandbox-router.yaml

Menginstal klien Python

Setelah komponen dalam cluster seperti Sandbox Router di-deploy, langkah persiapan terakhir adalah menginstal klien Python Agentic Sandbox di komputer lokal Anda. Ingatlah bahwa klien ini adalah library Python yang memungkinkan Anda membuat, menggunakan, dan menghapus sandbox secara terprogram. Anda akan menggunakannya di bagian berikutnya untuk menguji lingkungan:

  1. Membuat dan mengaktifkan lingkungan virtual Python:

    python3 -m venv .venv
source .venv/bin/activate

  2. Instal paket klien:

    pip install k8s_agent_sandbox

Menguji sandbox

Setelah semua komponen penyiapan tersedia, Anda kini dapat membuat dan berinteraksi dengan sandbox menggunakan klien Python Agentic Sandbox.

  1. Di direktori agent-sandbox, buat skrip Python bernama test_sandbox.py dengan konten berikut:

    from agentic_sandbox import SandboxClient

# Automatically tunnels to svc/sandbox-router-svc
with SandboxClient(
    template_name="python-runtime-template",
    namespace="default"
) as sandbox:
    print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
)

  2. Dari terminal Anda (dengan lingkungan virtual yang masih aktif), jalankan skrip pengujian:

    python3 test_sandbox.py

Anda akan melihat pesan "Hello from the sandboxed environment!" yang merupakan output dari sandbox.

Selamat! Anda telah berhasil menjalankan perintah shell di dalam sandbox yang aman. Dengan metode sandbox.run(), Anda dapat menjalankan perintah shell apa pun, dan Agent Sandbox menjalankan perintah dalam penghalang aman yang melindungi node cluster dan beban kerja lainnya dari kode yang tidak tepercaya. Hal ini memberikan cara yang aman dan andal bagi agen AI atau alur kerja otomatis apa pun untuk menjalankan tugas.

Saat Anda menjalankan skrip, SandboxClient akan menangani semua langkah untuk Anda. Skrip ini membuat resource SandboxClaim untuk memulai sandbox, menunggu sandbox siap, lalu menggunakan metode sandbox.run() untuk menjalankan perintah shell bash di dalam container yang aman. Kemudian, klien mengambil dan mencetak stdout dari perintah tersebut. Sandbox akan otomatis dihapus setelah program berjalan.

Saat resource SandboxClaim dibuat, Pod yang tersedia akan ditetapkan dari kumpulan pilihan alamat hangat ke objek Sandbox dan klaim ditandai siap. Kemudian, SandboxWarmPool akan otomatis mengisi ulang dirinya sendiri untuk mempertahankan jumlah replika yang dikonfigurasi.

Untuk memverifikasi apakah sandbox tertentu diklaim atau tersedia, periksa ownerReferences dalam metadata pod sandbox - jika nilai kolom kind adalah Sandbox, pod sedang digunakan. Jika nilai kolom kind adalah SandboxWarmPool, Pod tidak ada aktivitas dan menunggu untuk diklaim.

Membersihkan resource

Agar tidak dikenai biaya pada akun Google Cloud Anda, hapus cluster GKE yang Anda buat:

gcloud container clusters delete $CLUSTER_NAME --location=$GKE_LOCATION --quiet

Langkah berikutnya