Dokumen ini menunjukkan cara menjalankan kode buatan AI di sandbox terisolasi pada cluster Google Kubernetes Engine (GKE). Anda membuat template sandbox dan kumpulan sandbox siap pakai di cluster. Kemudian, Anda akan menjalankan skrip Python yang meminta sandbox dari kumpulan dan menjalankan perintah di sandbox. Skrip ini menggunakan klien Python Agent Sandbox, library untuk membuat dan mengelola sandbox.
Menjalankan kode yang tidak tepercaya di sandbox membantu melindungi sistem Anda dari potensi kerentanan dalam kode yang dihasilkan AI, meningkatkan kecepatan pengembangan, dan meningkatkan keamanan deployment Anda. Untuk ringkasan tentang cara Agent Sandbox di GKE mengisolasi kode buatan AI yang tidak tepercaya, lihat Tentang Agent Sandbox di GKE.
Biaya
Agent Sandbox di GKE adalah software open source yang dapat Anda gunakan tanpa biaya tambahan. Harga GKE berlaku untuk resource yang Anda buat, termasuk resource komputasi yang digunakan pengontrol Agent Sandbox.
Sebelum memulai
-
Di konsol Google Cloud , pada halaman pemilih project, pilih atau buat project Google Cloud .
Peran yang diperlukan untuk memilih atau membuat project
- Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
-
Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator
(
roles/resourcemanager.projectCreator), yang berisi izinresourcemanager.projects.create. Pelajari cara memberikan peran.
-
Pastikan penagihan diaktifkan untuk project Google Cloud Anda.
Aktifkan Kubernetes Engine API, jika belum diaktifkan.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin
serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.-
Di konsol Google Cloud , aktifkan Cloud Shell.
- Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan dokumen ini.
- Pastikan Anda memiliki cluster GKE yang telah menginstal pengontrol Agent Sandbox dan men-deploy Sandbox Router. Jika belum, selesaikan hanya bagian berikut dari
Menginstal
Agent Sandbox di GKE, lalu kembali ke
dokumen ini:
- Menentukan variabel lingkungan
- Membuat cluster GKE
- Menginstal Agent Sandbox
- Men-deploy Router Sandbox
SandboxTemplatedanSandboxWarmPoolAnda sendiri.
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 yang berguna berikut dengan menjalankan perintah berikut:
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
Berikut penjelasan tentang variabel lingkungan ini:
CLUSTER_NAME: nama cluster GKE Anda—misalnya,agent-sandbox-cluster.LOCATION: region atau zona Google Cloud tempat cluster GKE Anda berada. Jika Anda menggunakan cluster Autopilot, tetapkan ini ke region (misalnya,us-central1). Jika Anda menggunakan cluster Standard, tetapkan ini ke zona (misalnya,us-central1-a).
Men-deploy lingkungan dengan sandbox
Bagian ini menunjukkan cara membuat blueprint sandbox (resource SandboxTemplate), memverifikasi router jaringan, 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 Router Sandbox 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 apa pun. Perlu diketahui bahwa penggunaan
kubectl port-forward bukanlah solusi yang aman dan penggunaannya harus dibatasi pada
lingkungan pengembangan.
Membuat resource SandboxTemplate dan SandboxWarmPool
Sekarang, tentukan konfigurasi untuk sandbox Anda dengan membuat
resource SandboxTemplate dan resource SandboxWarmPool. Resource SandboxTemplate bertindak sebagai blueprint yang dapat digunakan kembali dan digunakan oleh pengontrol Agent Sandbox untuk membuat lingkungan sandbox yang konsisten dan telah dikonfigurasi sebelumnya. Resource SandboxWarmPool membantu memastikan bahwa jumlah Pod pra-pemanasan yang ditentukan selalu berjalan dan siap diklaim. Sandbox yang telah dihangatkan adalah Pod yang sedang berjalan dan telah diinisialisasi. Pra-inisialisasi ini
memungkinkan sandbox baru dibuat dalam waktu kurang dari satu detik, dan menghindari
latensi startup saat meluncurkan sandbox reguler:
Di Cloud Shell, buat file bernama
sandbox-template-and-pool.yamldengan konten berikut:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxTemplate metadata: name: python-sandbox-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/v1beta1 kind: SandboxWarmPool metadata: name: python-sandbox-warmpool namespace: default spec: replicas: 2 sandboxTemplateRef: name: python-sandbox-templateTerapkan manifes
SandboxTemplatedanSandboxWarmPool:kubectl apply -f sandbox-template-and-pool.yamlTunggu hingga sandbox warm pool siap:
kubectl wait sandboxwarmpool python-sandbox-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sNantinya dalam dokumen ini, klien Python akan membuat resource
SandboxClaim. Jika klien membuat klaim 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.
Memverifikasi Router Sandbox
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 mesin lokal Anda ke layanan Sandbox Router
yang berjalan di cluster. Pendekatan tunneling ini menghindari kebutuhan akan alamat IP publik atau penyiapan ingress yang kompleks, serta menyederhanakan interaksi dengan sandbox dari lingkungan lokal Anda.
Pastikan Sandbox Router berjalan di namespace agent-sandbox-system:
kubectl get deployment sandbox-router --namespace=agent-sandbox-system
Saat router berjalan, kolom READY menunjukkan bahwa semua replika sudah siap, misalnya 2/2. Jika perintah menampilkan error NotFound, deploy router dengan mengikuti langkah-langkah di bagian Men-deploy Router Sandbox.
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. Ingat 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:
Membuat dan mengaktifkan lingkungan virtual Python:
python3 -m venv .venv source .venv/bin/activateInstal paket klien. Gunakan versi yang sama dengan pengontrol Agent Sandbox:
pip install k8s-agent-sandbox==1.0.6
Menguji sandbox
Setelah semua komponen penyiapan siap, Anda kini dapat membuat dan berinteraksi dengan sandbox menggunakan klien Python Agentic Sandbox.
Buat skrip Python bernama
test_sandbox.pydengan konten berikut:from k8s_agent_sandbox import SandboxClient from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig # Tunnels to svc/sandbox-router-svc in the agent-sandbox-system namespace. # cleanup=True deletes the sandbox when the script exits. client = SandboxClient( connection_config=SandboxLocalTunnelConnectionConfig(), cleanup=True, ) sandbox = client.create_sandbox(warmpool="python-sandbox-warmpool", namespace="default") try: print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout) except Exception as e: print(f"An error occurred: {e}")Dari terminal Anda (dengan lingkungan virtual yang masih aktif), jalankan skrip pengujian:
python3 test_sandbox.py
Anda akan melihat pesan "Halo dari lingkungan sandbox!" yang merupakan output dari sandbox.
Selamat! Anda telah berhasil menjalankan perintah shell di dalam sandbox yang aman. Dengan menggunakan metode sandbox.commands.run(), Anda dapat menjalankan perintah shell apa pun, dan Agent Sandbox di GKE akan menjalankan perintah tersebut dalam batasan aman yang melindungi node cluster dan workload 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. Metode ini
membuat resource SandboxClaim untuk memulai sandbox, menunggu sandbox
siap, lalu menggunakan metode sandbox.commands.run() untuk menjalankan perintah
shell bash di dalam container yang aman. Klien kemudian mengambil dan mencetak
stdout dari perintah tersebut. Karena skrip menetapkan parameter cleanup ke True, klien akan menghapus sandbox saat program keluar.
Saat resource SandboxClaim dibuat, sandbox yang tersedia dari warm pool akan ditetapkan ke klaim dan klaim ditandai sebagai siap. Resource SandboxWarmPool kemudian akan otomatis mengisi ulang dirinya sendiri untuk mempertahankan jumlah replika yang dikonfigurasi.
Untuk memverifikasi apakah sandbox tertentu diklaim atau tersedia, periksa
ownerReferences di metadata resource Sandbox. Jika nilai kolom kind adalah SandboxClaim, sandbox sedang digunakan. Jika nilai kolom
kind adalah SandboxWarmPool, sandbox tidak ada aktivitas dan menunggu untuk
diklaim.
Menjalankan sandbox dalam produksi
Dalam dokumen ini, Anda akan berinteraksi dengan sandbox dari luar cluster menggunakan Cloud Shell. Klien Python menggunakan kredensial pengguna Anda untuk
melakukan autentikasi 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 orchestrator AI) bertanggung jawab untuk membuat dan mengelola resource sandbox. Untuk menggunakan Agent Sandbox di GKE 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 Workload Identity Federation for 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 memberi aplikasi identitas yang dapat Anda referensikan dalam kebijakan izin.
Pemilihan rute: permintaan dari klien Python di aplikasi pengontrol Anda harus mencapai Router Sandbox di cluster Anda. Dalam produksi, gunakan salah satu metode berikut untuk membuat koneksi jaringan:
- Jika aplikasi pengontrol berjalan di cluster yang sama, gunakan fungsi
SandboxDirectConnectionConfiguntuk menargetkan URL dan port yang digunakan layanan Sandbox Router. - Jika aplikasi pengontrol berjalan di luar cluster, gunakan
GKE Gateway
API untuk membuat load balancer internal
atau eksternal. Dalam kode klien, gunakan fungsi
SandboxGatewayConnectionConfiguntuk mereferensikan Gateway Anda.
Untuk mengetahui informasi selengkapnya tentang metode pemilihan rute ini, lihat contoh penggunaan di GitHub dan langkah-langkah deployment Gateway untuk router.
- Jika aplikasi pengontrol berjalan di cluster yang sama, gunakan fungsi
Akses sandbox ke resource Google Cloud : jika kode sandbox Anda perlu mengirim permintaan ke API Google Cloud , seperti Cloud Storage, gunakan kebijakan IAM dengan Workload Identity Federation for GKE untuk memberi ServiceAccount Kubernetes yang digunakan Pod sandbox izin yang diperlukan untuk akses tersebut. Karena kebijakan jaringan default memblokir akses ke server metadata Google Cloud (
169.254.169.254), Anda harus menyesuaikan kebijakan jaringan untuk mengizinkan traffic ini.Batasan Kebijakan Jaringan: secara default, Agent Sandbox di GKE menerapkan postur jaringan Aman secara Default yang ketat (
networkPolicyManagement: Managed). Batasan berikut berlaku dalam postur ini:- Ingress diblokir dari semua sumber kecuali Router Sandbox yang ditetapkan (Pod yang memiliki label
app: sandbox-routerdi namespaceagent-sandbox-system). - Egress diizinkan ke internet publik, tetapi egress ke rentang LAN pribadi (RFC 1918), DNS cluster internal (CoreDNS), dan Server Metadata Penyedia Cloud (
169.254.0.0/16) diblokir secara eksplisit.
Untuk menggunakan Workload Identity Federation for GKE atau mengakses resource pribadi lainnya, Anda harus menentukan kebijakan jaringan kustom di resource
SandboxTemplate. Untuk mengetahui detail konfigurasi terperinci dan template yang dapat disesuaikan (seperti sandbox air-gapped atau Workload Identity Federation for GKE untuk integrasi GKE), lihat Pengelolaan Kebijakan Jaringan Agent Sandbox.- Ingress diblokir dari semua sumber kecuali Router Sandbox yang ditetapkan (Pod yang memiliki label
Kebijakan keamanan sandbox
Secara default, Agent Sandbox di GKE tidak menerapkan kebijakan keamanan ke sandbox. Untuk membantu menerapkan setelan isolasi untuk sandbox Anda,
terapkan secure-sandbox-policy Kubernetes Validating Admission
Policy (VAP) yang direkomendasikan dari repositori GitHub Agent Sandbox. Untuk mengetahui petunjuknya, lihat Menerapkan kebijakan keamanan yang direkomendasikan.
Kebijakan ini menerapkan persyaratan isolasi, seperti mewajibkan gVisor, menonaktifkan
hostNetwork, dan memblokir volume hostPath. Kebijakan ini juga menerapkan
persyaratan penguatan, seperti menghapus semua kemampuan, mencegah
penambahan kemampuan baru, dan mewajibkan container untuk berjalan sebagai non-root dan
menetapkan batas resource. Untuk mengetahui daftar lengkap persyaratan, lihat
Persyaratan deployment Agent Sandbox di GKE.
Mengubah atau menghapus batasan kebijakan
Karena Anda menerapkan kebijakan sendiri, Anda dapat mengubahnya agar sesuai dengan workload Anda. Jika workload Anda memerlukan pengecualian dari beberapa aturan, Anda dapat mengubah kebijakan untuk menghapus batasan tertentu atau menghapus binding kebijakan sepenuhnya. Menghapus batasan akan mengurangi isolasi yang diberikan oleh kebijakan, jadi hapus hanya batasan yang diperlukan workload Anda.
Untuk mengubah kebijakan dan menghapus batasan tertentu (misalnya, untuk mengizinkan
container berjalan sebagai root atau menghilangkan batas resource), edit
resource ValidatingAdmissionPolicy:
kubectl edit validatingadmissionpolicy secure-sandbox-policy
Di editor teks yang terbuka, temukan bagian validations dan hapus atau
ubah ekspresi batasan yang memblokir workload Anda.
Atau, jika Anda ingin berhenti menerapkan kebijakan di cluster, hapus binding kebijakan:
kubectl delete validatingadmissionpolicybinding secure-sandbox-binding
Masalah umum
Bagian ini menjelaskan masalah umum saat menggunakan Agent Sandbox di GKE, serta cara menyelesaikan atau mengatasinya.
Blokir kemampuan kebijakan keamanan saat menggunakan mesh layanan
Jika Anda menerapkan kebijakan keamanan yang direkomendasikan dan mencoba men-deploy sandbox yang terintegrasi dengan sidecar mesh layanan (misalnya, Envoy atau Istio), pembuatan sandbox mungkin diblokir oleh kebijakan dengan error seperti berikut:
sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'secure-sandbox-policy' with binding 'secure-sandbox-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.
- Penyebab: Sidecar mesh layanan sering kali menggunakan container init, seperti
istio-initatauproxy-init. Container init ini memerlukan kemampuan sepertiNET_ADMINatauNET_RAWuntuk mengonfigurasi aturaniptablesuntuk pemilihan rute egress transparan.secure-sandbox-policyValidatingAdmissionPolicy memblokir semua penambahan kemampuan di semua jenis container. - Solusi: karena Anda mengelola kebijakan ini di cluster, Anda dapat
mengubah
ValidatingAdmissionPolicyuntuk mengizinkan container init tepercaya tertentu meminta kemampuanNET_ADMINdanNET_RAW. Untuk mengetahui petunjuk tentang cara mengubah atau menghapus batasan kebijakan, lihat Mengubah atau menghapus batasan kebijakan. Misalnya, Anda dapat memperbarui ekspresi atau variabel validasi kebijakan untuk mengecualikan nama container tepercaya dari aturan kemampuan.
Latensi atau waktu tunggu egress saat terhubung ke Google API melalui IPv6
Workload di dalam sandbox mungkin mengalami waktu tunggu koneksi atau latensi tinggi, hingga dua menit, saat mencoba terhubung ke resource eksternal atau Google API (seperti Vertex AI atau Cloud Storage).
- Penyebab: jika cluster GKE Anda mengaktifkan IPv6 stack ganda, resolusi DNS untuk Google API akan menampilkan alamat IPv4 (A) dan IPv6 (AAAA). Beberapa algoritma di mesin runtime, seperti Node.js, mencoba terhubung melalui IPv6 terlebih dahulu. Jika VPC GKE Anda tidak memiliki rute egress IPv6 yang valid, seperti Cloud NAT atau gateway internet untuk IPv6, koneksi TCP akan berhenti merespons hingga waktu tunggu TCP SYN habis. Kemudian, koneksi TCP akan beralih ke IPv4.
Penyelesaian: untuk menyelesaikan masalah ini, lakukan salah satu tindakan berikut:
- Konfigurasi egress IPv6: untuk mengizinkan traffic IPv6 keluar kembali ke cluster, konfigurasikan Cloud NAT IPv6 atau gateway internet yang valid di jaringan VPC Anda.
Memprioritaskan IPv4 dalam workload: untuk memprioritaskan resolusi DNS IPv4, konfigurasikan runtime workload Anda. Misalnya, dalam aplikasi Node.js, Anda dapat menetapkan variabel lingkungan berikut dalam definisi
SandboxTemplate:env: - name: NODE_OPTIONS value: "--dns-result-order=ipv4first --no-network-family-autoselection"
Membersihkan resource
Agar akun Google Cloud Anda tidak dikenai biaya, Anda harus menghapus cluster GKE yang Anda buat:
gcloud container clusters delete ${CLUSTER_NAME} \
--location=${LOCATION} \
--quiet
Langkah berikutnya
- Pelajari cara Menyimpan dan memulihkan Agent Sandbox di lingkungan GKE dengan snapshot Pod.
- Pelajari lebih lanjut project open source Agent Sandbox di GitHub.
- Pelajari cara menggunakan Kata Containers open source dengan Agent Sandbox di GKE. Kata Containers bukan produk Google Cloud . Jika Anda menginstal dan menggunakan software ini, Anda bertanggung jawab atas pengelolaan dan pemecahan masalah. Dukungan dan SLA Google tidak berlaku untuk Kata Containers.
- Untuk memahami teknologi dasar yang menyediakan isolasi keamanan untuk workload Anda, lihat GKE Sandbox.
- Untuk mengetahui informasi selengkapnya tentang cara meningkatkan keamanan cluster dan workload Anda, lihat Ringkasan keamanan GKE.