Mengisolasi eksekusi kode AI dengan Sandbox Agen

Dokumen ini memberikan petunjuk untuk men-deploy lingkungan developer dan menggunakan klien Python Agent Sandbox di cluster Google Kubernetes Engine (GKE).

Untuk mengetahui ringkasan cara fitur Agent Sandbox mengisolasi kode buatan AI yang tidak tepercaya, lihat artikel Tentang GKE Agent Sandbox.

Biaya

Agent Sandbox ditawarkan tanpa biaya tambahan di GKE. Harga GKE berlaku untuk resource yang Anda buat.

Sebelum memulai

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

    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 Cloud de Confiance Anda.

  3. Aktifkan Artifact Registry, 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 Cloud de Confiance , aktifkan Cloud Shell.

    Aktifkan Cloud Shell

  5. Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini.
  6. Anda harus memiliki cluster GKE dengan fitur Agent Sandbox yang diaktifkan. Jika Anda belum memilikinya, ikuti petunjuk di Mengaktifkan Agent Sandbox di GKE untuk membuat cluster baru atau mengupdate cluster yang ada.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat dan mengelola sandbox, minta administrator untuk memberi Anda peran IAM Kubernetes Engine Admin (roles/container.admin) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

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 LOCATION="us-central1"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"

Berikut penjelasan variabel lingkungan ini:

  • PROJECT_ID: ID Cloud de Confiance by S3NS project Anda saat ini. Menentukan variabel ini membantu memastikan bahwa semua resource, seperti cluster GKE Anda, dibuat di project yang benar.
  • CLUSTER_NAME: nama cluster GKE Anda—misalnya, agent-sandbox-cluster.
  • LOCATION: Cloud de Confiance by S3NS region atau zona tempat cluster GKE Anda berada. Tetapkan ini ke region (misalnya, us-central1) jika Anda menggunakan cluster Autopilot, atau zona (misalnya, us-central1-a) jika Anda menggunakan cluster Standard.
  • 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 lingkungan dalam sandbox

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 berfungsi sebagai blueprint yang dapat digunakan kembali yang digunakan pengontrol Sandbox Agen untuk membuat lingkungan sandbox yang konsisten dan telah dikonfigurasi sebelumnya. Resource SandboxWarmPool membantu memastikan bahwa sejumlah Pod yang dipanaskan sebelumnya 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 peluncuran saat memulai 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
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      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"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      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: 1
  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:latest-main
        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: "100m"
            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

  3. Pastikan deployment Sandbox Router berjalan dengan benar:

    kubectl get deployment sandbox-router-deployment

    Tunggu hingga deployment menampilkan 2/2 atau 1/1 di kolom READY.

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 k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

# Automatically tunnels to svc/sandbox-router-svc
client = SandboxClient(
    connection_config=SandboxLocalTunnelConnectionConfig()
)

sandbox = client.create_sandbox(template="python-runtime-template", namespace="default")
try:
    print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  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. Klien kemudian 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 hangat ke objek Sandbox dan klaim ditandai siap. SandboxWarmPool kemudian 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.

Menjalankan sandbox dalam produksi

Dalam dokumen ini, Anda berinteraksi dengan sandbox dari luar cluster menggunakan Cloud Shell. Klien Python menggunakan kredensial pengguna Anda untuk mengautentikasi ke cluster dan mengelola resource sandbox, serta menggunakan perintah kubectl port-forward untuk membuat koneksi dengan sandbox. Langkah-langkah ini berfungsi dengan baik untuk skenario pengembangan.

Dalam skenario produksi, aplikasi pengontrol (seperti pengelola AI) bertanggung jawab untuk membuat dan mengelola resource sandbox. Untuk menggunakan Sandbox Agen dalam produksi, pertimbangkan hal berikut:

  • Autentikasi: aplikasi pengontrol Anda harus melakukan autentikasi ke server API cluster untuk menjalankan sandbox. Cara Anda mengonfigurasi autentikasi bergantung pada tempat aplikasi pengontrol berjalan, sebagai berikut:

    • Jika aplikasi pengontrol berjalan sebagai Pod di cluster yang sama, gunakan RBAC Kubernetes atau Federasi Workload Identity untuk GKE dengan kebijakan IAM untuk memberikan izin yang diperlukan kepada ServiceAccount Kubernetes Pod untuk memantau sandbox atau menemukan endpoint jaringan.
    • Jika aplikasi pengontrol berjalan di luar cluster, gunakan Workload Identity Federation, atau akun layanan IAM untuk memberikan identitas pada aplikasi yang dapat Anda referensikan dalam kebijakan izin.

  • Perutean: permintaan dari klien Python di aplikasi pengontrol Anda harus mencapai Sandbox Router di cluster Anda. Dalam produksi, gunakan salah satu metode berikut untuk membuat koneksi jaringan:

    • Jika aplikasi pengontrol berjalan di cluster yang sama, gunakan fungsi SandboxDirectConnectionConfig untuk menargetkan URL dan port yang digunakan oleh layanan Sandbox Router.
    • Jika aplikasi pengontrol berjalan di luar cluster, gunakan GKE Gateway API untuk membuat load balancer internal atau eksternal. Dalam kode klien Anda, gunakan fungsi SandboxGatewayConnectionConfig untuk mereferensikan Gateway Anda.

    Untuk mengetahui informasi selengkapnya tentang metode perutean ini, lihat contoh penggunaan di GitHub dan Langkah-langkah deployment gateway untuk router.

  • Akses sandbox ke Cloud de Confiance resource: jika kode sandbox Anda perlu mengirim permintaan ke Cloud de Confiance API, seperti Cloud Storage, gunakan kebijakan IAM dengan Federasi Workload Identity untuk GKE untuk memberikan izin yang diperlukan untuk akses tersebut kepada ServiceAccount Kubernetes yang digunakan Pod sandbox.

Membersihkan resource

Agar tidak dikenai biaya pada akun Cloud de Confiance by S3NS Anda, hapus cluster GKE yang Anda buat:

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

Langkah berikutnya