Anda dapat men-deploy lingkungan developer untuk menggunakan klien Python Agent Sandbox di cluster Google Kubernetes Engine (GKE). Penyiapan ini membantu Anda menjalankan dan menguji kode buatan AI dengan aman dengan mengisolasi kode yang tidak tepercaya dalam lingkungan Python sandbox. Isolasi ini sangat penting untuk melindungi sistem Anda dari potensi kerentanan dalam kode buatan AI, meningkatkan kecepatan pengembangan, dan memastikan deployment yang aman. Untuk mengetahui ringkasan tentang cara fitur Agent Sandbox mengisolasi kode buatan AI yang tidak tepercaya, lihat Tentang GKE Agent Sandbox.
Biaya
Agent Sandbox ditawarkan tanpa biaya tambahan di GKE. Harga GKE berlaku untuk resource yang Anda buat.
Sebelum memulai
-
Di Cloud de Confiance konsol, pada halaman pemilih project, pilih atau buat Cloud de Confiance project.
Peran yang diperlukan untuk memilih atau membuat project
- Memilih 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 Project Creator
(
roles/resourcemanager.projectCreator), yang berisi izinresourcemanager.projects.create. Pelajari cara memberikan peran.
-
Pastikan penagihan diaktifkan untuk Cloud de Confiance project Anda.
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 izinserviceusage.services.enable. Pelajari cara memberikan peran.-
Di Cloud de Confiance konsol, aktifkan Cloud Shell.
- Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini.
- Anda harus memiliki cluster GKE dengan fitur Agent Sandbox diaktifkan. Jika Anda tidak 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 tentang variabel lingkungan ini:
PROJECT_ID: ID project Anda saat ini. Cloud de Confiance by S3NS 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: region atau zona tempat cluster GKE Anda berada. Cloud de Confiance by S3NS 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 workload 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 memilih di antara berbagai opsi, lihat Panduan perbandingan dan resource kelompok mesin.
Men-deploy lingkungan sandbox
Bagian ini menunjukkan cara membuat blueprint 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 apa pun. Perlu diketahui bahwa penggunaan kubectl port-forward bukanlah solusi yang aman dan penggunaannya harus dibatasi untuk lingkungan pengembangan.
Membuat SandboxTemplate dan SandboxWarmPool
Sekarang Anda menentukan konfigurasi untuk sandbox dengan membuat resource SandboxTemplate dan SandboxWarmPool. SandboxTemplate bertindak sebagai blueprint yang dapat digunakan kembali yang digunakan oleh pengontrol Agent Sandbox untuk membuat lingkungan sandbox yang konsisten dan telah dikonfigurasi sebelumnya. Resource SandboxWarmPool membantu memastikan bahwa jumlah Pod yang telah diaktifkan selalu berjalan dan siap untuk diklaim. Sandbox yang telah diaktifkan adalah Pod yang 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/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-templateTerapkan manifes
SandboxTemplatedanSandboxWarmPool: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 kompleks, dan menyederhanakan interaksi dengan sandbox dari lingkungan lokal Anda.
Ikuti langkah-langkah berikut untuk men-deploy Sandbox Router:
Di Cloud Shell, buat file bernama
sandbox-router.yamldengan 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: 1000Terapkan manifes untuk men-deploy router ke cluster Anda:
kubectl apply -f sandbox-router.yamlPastikan deployment Sandbox Router berjalan dengan benar:
kubectl get deployment sandbox-router-deploymentTunggu 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:
Membuat dan mengaktifkan lingkungan virtual Python:
python3 -m venv .venv source .venv/bin/activateInstal paket klien:
pip install k8s-agent-sandbox
Menguji sandbox
Dengan semua komponen penyiapan sudah ada, Anda kini dapat membuat dan berinteraksi dengan sandbox menggunakan klien Python Agentic Sandbox.
Di direktori
agent-sandbox, buat skrip Python bernamatest_sandbox.pydengan 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}")Dari terminal Anda (dengan lingkungan virtual 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 menggunakan metode sandbox.run(), Anda dapat menjalankan perintah shell apa pun, dan Agent Sandbox menjalankan perintah dalam batas 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. 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 warm pool ke objek Sandbox dan klaim akan ditandai siap. SandboxWarmPool kemudian akan otomatis diisi ulang untuk mempertahankan jumlah replika yang dikonfigurasi.
Untuk memverifikasi apakah sandbox tertentu diklaim atau tersedia, periksa ownerReferences di metadata pod sandbox - jika nilai kolom kind adalah Sandbox, pod sedang digunakan. Jika nilai kolom kind adalah SandboxWarmPool, Pod tidak aktif 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 orkestrator AI) bertanggung jawab untuk membuat dan mengelola resource sandbox. Untuk menggunakan Agent Sandbox 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 untuk GKE dengan kebijakan IAM untuk memberikan izin yang diperlukan kepada Kubernetes ServiceAccount 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 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
SandboxDirectConnectionConfiguntuk menargetkan URL dan port yang digunakan oleh layanan Sandbox Router. - Jika aplikasi pengontrol berjalan di luar cluster, gunakan
the
GKE Gateway API
untuk membuat load balancer internal atau eksternal. Dalam kode klien Anda, gunakan fungsi
SandboxGatewayConnectionConfiguntuk mereferensikan Gateway Anda.
Untuk mengetahui informasi selengkapnya tentang metode perutean 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 Cloud de Confiance resource: jika kode sandbox Anda perlu mengirim permintaan ke Cloud de Confiance API, seperti Cloud Storage, gunakan kebijakan IAM dengan Workload Identity Federation untuk GKE guna memberikan izin yang diperlukan untuk akses tersebut kepada Kubernetes ServiceAccount yang digunakan oleh Pod sandbox. Karena kebijakan jaringan default memblokir akses ke server metadata (
169.254.169.254), Anda harus menyesuaikan kebijakan jaringan untuk mengizinkan traffic ini. Cloud de Confiance by S3NSBatasan Kebijakan Jaringan: secara default, Agent Sandbox menerapkan postur jaringan Secure-by-Default yang ketat (
networkPolicyManagement: Managed). Batasan berikut berlaku dalam postur ini:- Ingress diblokir dari semua sumber kecuali Sandbox Router yang ditentukan.
- 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 untuk GKE atau mengakses resource pribadi lainnya, Anda harus menentukan kebijakan jaringan kustom di
SandboxTemplate. Untuk mengetahui detail konfigurasi mendetail dan template yang dapat disesuaikan (seperti sandbox yang terisolasi atau integrasi Workload Identity Federation untuk GKE), lihat Pengelolaan Kebijakan Jaringan Agent Sandbox.
Kebijakan keamanan sandbox
Untuk membantu memastikan lingkungan Secure-by-Default, addon GKE Agent
Sandbox menggunakan Kebijakan Penerimaan Validasi (VAP) Kubernetes untuk menerapkan
batasan keamanan pada Sandbox dan SandboxTemplate resource. Kebijakan ini diterapkan secara otomatis.
Addon membagi penerapan keamanan menjadi model kebijakan dua tingkat untuk fleksibilitas yang lebih baik. Bagian berikut menjelaskan kebijakan ini: kebijakan inti yang dikelola secara ketat dan kebijakan hardening yang dapat disesuaikan.
Kebijakan keamanan inti (sandbox-core-policy)
Kebijakan keamanan inti menerapkan persyaratan isolasi yang membantu melindungi integritas sandbox. Kebijakan ini mencakup aturan yang mewajibkan penggunaan gVisor, isolasi jaringan seperti menonaktifkan hostNetwork, dan isolasi sistem file seperti memblokir hostPath. Karena GKE mengelola kebijakan ini melalui setelan addonmanager.kubernetes.io/mode: Reconcile, Anda tidak dapat mengubah atau mengganti aturan inti ini.
Kebijakan keamanan hardening (sandbox-hardening-policy)
Kebijakan keamanan hardening memberikan praktik terbaik keamanan dan opsi pengelolaan tambahan. Kebijakan ini menerapkan batasan seperti menghilangkan semua kemampuan, mencegah penambahan kemampuan baru, dan mewajibkan container berjalan sebagai non-root dengan batas resource. GKE men-deploy kebijakan ini dalam mode EnsureExists melalui setelan addonmanager.kubernetes.io/mode: EnsureExists. Setelan ini berarti GKE membuat kebijakan jika tidak ada, tetapi Anda dapat mengubah atau menghapus kebijakan atau binding-nya jika diperlukan.
Mengubah atau menghapus batasan hardening
Karena kebijakan hardening di-deploy dalam mode EnsureExists, GKE membuat kebijakan jika tidak ada, tetapi tidak akan menimpa perubahan Anda. Jika workload Anda memerlukan pengecualian dari aturan hardening ini, Anda dapat mengubah kebijakan untuk menghapus batasan tertentu atau menghapus binding kebijakan sepenuhnya.
Untuk mengubah kebijakan hardening dan menghapus batasan tertentu (misalnya, untuk mengizinkan container berjalan sebagai root atau menghilangkan batas resource), edit resource ValidatingAdmissionPolicy:
kubectl edit validatingadmissionpolicy sandbox-hardening-policy
Di editor teks yang terbuka, temukan bagian validations dan hapus atau ubah ekspresi batasan yang memblokir workload Anda.
Atau, jika Anda ingin menonaktifkan kebijakan hardening sepenuhnya untuk cluster Anda, hapus binding kebijakan:
kubectl delete validatingadmissionpolicybinding sandbox-hardening-binding
Masalah umum
Bagian ini menjelaskan masalah umum saat menggunakan Agent Sandbox di GKE, dan cara mengatasi atau mengatasinya.
Kebijakan keamanan memblokir kemampuan saat menggunakan service mesh
Jika Anda mencoba men-deploy sandbox yang terintegrasi dengan sidecar service mesh (misalnya, Envoy atau Istio), pembuatan sandbox mungkin diblokir oleh kebijakan keamanan hardening dengan error seperti berikut:
sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'sandbox-hardening-policy' with binding 'sandbox-hardening-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.
- Penyebab: Sidecar service mesh sering menggunakan container init, seperti
istio-initatauproxy-init. Container init ini memerlukan kemampuan sepertiNET_ADMINatauNET_RAWuntuk mengonfigurasiiptablesaturan untuk perutean egress transparan. Secara default,sandbox-hardening-policyGKE memblokir semua penambahan kemampuan di semua jenis container. - Solusi: karena kebijakan hardening GKE di-deploy
dalam mode
EnsureExists, Anda dapat mengubahValidatingAdmissionPolicyuntuk mengizinkan container init tepercaya tertentu meminta kemampuanNET_ADMINdanNET_RAW. Untuk mengetahui petunjuk tentang cara mengubah atau menghapus batasan hardening ini, lihat Mengubah atau menghapus batasan hardening. 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) alamat. 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 (untuk mengetahui info selengkapnya, lihat https://developers.google.com/style/word-list#hang) hingga waktu tunggu TCP SYN berakhir. Kemudian, koneksi TCP akan kembali ke IPv4.
Penyelesaian: untuk menyelesaikan masalah ini, lakukan salah satu tindakan berikut:
- Mengonfigurasi egress IPv6: untuk mengizinkan traffic IPv6 keluar kembali ke cluster, konfigurasikan Cloud NAT IPv6 atau gateway internet yang valid di jaringan VPC Anda.
Memilih IPv4 dalam workload: untuk memilih resolusi DNS IPv4, konfigurasikan runtime workload Anda. Misalnya, di 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
Untuk menghindari tagihan ke Cloud de Confiance by S3NS akun Anda, Anda harus menghapus cluster GKE yang Anda buat:
gcloud container clusters delete $CLUSTER_NAME --location=$LOCATION --quiet
Langkah berikutnya
- Pelajari cara Menyimpan dan memulihkan lingkungan Agent Sandbox dengan snapshot Pod.
- Pelajari lebih lanjut project open source Agent Sandbox di GitHub.
- Pelajari cara menggunakan Kata Containers open source dengan Agent Sandbox. Kata Containers bukan Cloud de Confiance produk. 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 memberikan isolasi keamanan untuk workload Anda, lihat GKE Sandbox.
- Untuk mengetahui informasi selengkapnya tentang cara meningkatkan keamanan untuk cluster dan workload Anda, lihat Ringkasan keamanan GKE.