Dokumen ini menjelaskan cara mengaktifkan Agent Sandbox di Google Kubernetes Engine (GKE) dalam cluster. Dokumen ini juga menjelaskan cara membuat lingkungan sandbox di cluster untuk menjalankan kode yang tidak tepercaya dengan aman.
Untuk mengetahui 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 ditawarkan tanpa biaya tambahan. Harga GKE berlaku untuk resource yang Anda buat.
Untuk menghindari tagihan yang tidak perlu, pastikan Anda menonaktifkan GKE atau menghapus project setelah menyelesaikan dokumen ini.
Sebelum memulai
-
Di Google Cloud konsol, pada halaman pemilih project, pilih atau buat Google Cloud 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 Pembuat Project
(
roles/resourcemanager.projectCreator), yang berisi izinresourcemanager.projects.create. Pelajari cara memberikan peran.
-
Pastikan penagihan diaktifkan untuk Google Cloud project Anda.
Aktifkan Artifact Registry, Google Kubernetes Engine API, jika ada yang 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 Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.-
Di Google Cloud konsol, aktifkan Cloud Shell.
- Pastikan cluster Anda menjalankan GKE versi 1.36.3-gke.1767000 atau yang lebih baru (mendukung
v1beta1API).
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 CLUSTER_VERSION="1.36.3-gke.1767000"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"
Berikut penjelasan tentang variabel lingkungan ini:
PROJECT_ID: ID project Anda saat ini. Google Cloud Menentukan variabel ini akan 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: Google Cloud region atau zona tempat cluster GKE Anda dibuat. Tetapkan variabel ini ke region (misalnya,us-central1) jika Anda membuat cluster Autopilot, atau zona (misalnya,us-central1-a) jika Anda membuat cluster Standar.CLUSTER_VERSION: versi GKE yang akan dijalankan cluster Anda (1.36.3-gke.1767000atau yang lebih baru).NODE_POOL_NAME: nama node pool yang akan menjalankan workload sandbox—misalnya,agent-sandbox-pool. Variabel ini hanya diperlukan jika Anda membuat cluster GKE Standar.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. Variabel ini hanya diperlukan jika Anda membuat cluster GKE Standar.
Mengaktifkan Agent Sandbox di GKE
Anda dapat mengaktifkan Agent Sandbox di GKE saat membuat cluster baru, atau saat mengupdate cluster yang ada.
Mengaktifkan Agent Sandbox di GKE saat membuat cluster baru
Sebaiknya gunakan cluster Autopilot untuk pengalaman Kubernetes yang dikelola sepenuhnya. Untuk memilih mode operasi GKE yang paling sesuai untuk workload Anda, lihat Memilih mode operasi GKE.
Autopilot
Untuk membuat cluster GKE Autopilot baru dengan Agent Sandbox di GKE yang diaktifkan, sertakan flag --enable-agent-sandbox:
gcloud beta container clusters create-auto ${CLUSTER_NAME} \
--location=${LOCATION} \
--cluster-version=${CLUSTER_VERSION} \
--enable-agent-sandbox
Untuk cluster Autopilot, pastikan variabel lingkungan LOCATION ditetapkan ke region (misalnya, us-central1).
Standar
Untuk membuat cluster GKE Standar baru dengan Agent Sandbox di GKE yang diaktifkan, Anda harus membuat cluster, menambahkan node pool dengan gVisor yang diaktifkan, lalu mengaktifkan Agent Sandbox di GKE. Untuk menghemat biaya, sebaiknya buat cluster zona dengan satu node per pool:
Buat cluster:
gcloud beta container clusters create ${CLUSTER_NAME} \ --location=${LOCATION} \ --num-nodes=1 \ --cluster-version=${CLUSTER_VERSION}Untuk cluster Standar ini, pastikan variabel lingkungan
LOCATIONditetapkan ke zona (misalnya,us-central1-a).Buat node pool terpisah dengan gVisor yang diaktifkan:
gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --machine-type=${MACHINE_TYPE} \ --location=${LOCATION} \ --num-nodes=1 \ --image-type=cos_containerd \ --sandbox=type=gvisorLOCATIONharus merupakan zona yang sama dengan yang Anda gunakan saat membuat cluster.Update cluster untuk mengaktifkan Agent Sandbox di GKE:
gcloud beta container clusters update ${CLUSTER_NAME} \ --location=${LOCATION} \ --enable-agent-sandbox
Mengaktifkan Agent Sandbox di GKE saat mengupdate cluster yang ada
Untuk mengaktifkan Agent Sandbox di GKE dalam cluster yang ada, cluster harus menjalankan versi 1.36.3-gke.1767000 atau yang lebih baru, yang mendukung v1beta1 API.
Pastikan variabel lingkungan LOCATION Anda ditetapkan ke region atau zona tempat cluster yang ada berada.
Jika Anda menggunakan cluster GKE Standar, Agent Sandbox di GKE bergantung pada gVisor. Jika cluster Standar Anda tidak memiliki node pool yang mengaktifkan gVisor, Anda harus membuatnya terlebih dahulu:
gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --machine-type=${MACHINE_TYPE} \ --location=${LOCATION} \ --image-type=cos_containerd \ --sandbox=type=gvisorUpdate cluster untuk mengaktifkan Agent Sandbox di GKE:
gcloud beta container clusters update ${CLUSTER_NAME} \ --location=${LOCATION} \ --enable-agent-sandbox
Memverifikasi konfigurasi
Anda dapat memverifikasi apakah Agent Sandbox di GKE diaktifkan dengan memeriksa deskripsi cluster.
gcloud beta container clusters describe ${CLUSTER_NAME} \
--location=${LOCATION} \
--format="value(addonsConfig.agentSandboxConfig.enabled)"
Jika Anda membuat cluster Autopilot, lokasinya adalah region (misalnya, us-central1). Jika Anda membuat cluster Standar, lokasinya adalah zona (misalnya, us-central1-a).
Jika fitur berhasil diaktifkan, perintah akan menampilkan True.
Persyaratan deployment Agent Sandbox di GKE
Agar berhasil men-deploy workload, seperti Sandbox atau SandboxTemplate,
manifes YAML Anda harus menyertakan setelan keamanan dan konfigurasi tertentu.
GKE menerapkan persyaratan ini menggunakan Kebijakan Penerimaan Validasi (VAP). Jika persyaratan ini tidak terpenuhi, pengontrol penerimaan akan menolak deployment.
Konfigurasi yang diperlukan
Manifes deployment Anda harus menyertakan setelan berikut:
runtimeClassName: gvisor: memastikan Pod berjalan di sandbox gVisor.automountServiceAccountToken: false: mencegah Pod memasang token akun layanan default secara otomatis.securityContext.runAsNonRoot: true: memastikan container tidak berjalan sebagai pengguna root.securityContext.capabilities.drop: ["ALL"]: menghapus semua kemampuan Linux dari container.resources.limits: Anda harus menentukan batas CPU dan memori untuk mencegah potensi skenario penolakan layanan (DoS).nodeSelector: harus menargetkansandbox.gke.io/runtime: gvisor.tolerations: harus menyertakan toleransi untuk taintsandbox.gke.io/runtime=gvisor:NoSchedule.
Konfigurasi yang dilarang
Manifes deployment Anda tidak boleh menyertakan salah satu hal berikut:
hostNetwork: true,hostPID: true, atauhostIPC: true.privileged: truedalam konteks keamanan container.- Volume
HostPath. - Kemampuan yang ditambahkan (
capabilities.add). - Setelan
hostPort. - Sysctl kustom.
- Volume yang diproyeksikan untuk token atau sertifikat akun layanan.
Men-deploy lingkungan sandbox
Sebaiknya deploy lingkungan sandbox dengan menentukan SandboxTemplate dan menjaga instance yang sudah di-warm up tetap siap menggunakan SandboxWarmPool. Kemudian, Anda dapat meminta instance dari node pool warm ini menggunakan SandboxClaim. Atau, Anda dapat membuat Sandbox secara langsung, tetapi pendekatan ini tidak mendukung warm pool.
SandboxTemplate, SandboxWarmPool, SandboxClaim, dan Sandbox adalah resource kustom Kubernetes.
Direkomendasikan: Membuat SandboxTemplate dan SandboxWarmPool
SandboxTemplate berfungsi sebagai cetak biru yang dapat digunakan kembali. SandboxWarmPool membantu memastikan bahwa jumlah Pod yang sudah di-warm up selalu berjalan dan siap diklaim. Penggunaan resource kustom ini meminimalkan latensi startup.
Untuk men-deploy lingkungan sandbox dengan membuat SandboxTemplate dan SandboxWarmPool, selesaikan langkah-langkah berikut:
Di Cloud Shell, buat file bernama
sandbox-template.yamldengan konten berikut:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxTemplate metadata: name: python-runtime-template namespace: default spec: podTemplate: metadata: labels: sandbox-type: python-runtime spec: runtimeClassName: gvisor # Required 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: runtime image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 resources: requests: cpu: "250m" memory: "512Mi" limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required restartPolicy: OnFailureTerapkan manifes
SandboxTemplate:kubectl apply -f sandbox-template.yamlBuat file bernama
sandbox-warmpool.yamldengan konten berikut:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxWarmPool metadata: name: python-runtime-warmpool namespace: default labels: app: python-runtime-warmpool spec: replicas: 2 sandboxTemplateRef: # This must match the name of the SandboxTemplate. name: python-runtime-templateTerapkan manifes
SandboxWarmPool:kubectl apply -f sandbox-warmpool.yaml
Membuat SandboxClaim
SandboxClaim meminta sandbox dari warm pool. Karena Anda membuat warm pool, Sandbox yang dibuat akan menggunakan Pod yang berjalan dari pool, bukan memulai Pod baru.
Untuk meminta sandbox dari warm pool dengan membuat SandboxClaim, selesaikan langkah-langkah berikut:
Buat file bernama
sandbox-claim.yamldengan konten berikut:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxClaim metadata: name: sandbox-claim namespace: default spec: warmPoolRef: # This must match the name of the SandboxWarmPool. name: python-runtime-warmpoolTerapkan manifes
SandboxClaim:kubectl apply -f sandbox-claim.yamlPastikan sandbox, klaim, dan warm pool sudah siap:
kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
Alternatif: Membuat Sandbox secara langsung
Jika tidak memerlukan waktu startup cepat yang disediakan oleh warm pool, Anda dapat men-deploy Sandbox secara langsung tanpa menggunakan template.
Untuk men-deploy lingkungan sandbox dengan membuat Sandbox secara langsung, selesaikan langkah-langkah berikut:
Buat file bernama
sandbox.yamldengan konten berikut:apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: sandbox-example-2 spec: replicas: 1 podTemplate: metadata: labels: sandbox: sandbox-example spec: runtimeClassName: gvisor restartPolicy: OnFailure automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 # Required if image defaults to root (e.g. busybox) nodeSelector: sandbox.gke.io/runtime: gvisor tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: my-container image: busybox command: ["/bin/sh", "-c"] args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"] securityContext: capabilities: drop: ["ALL"] # Required allowPrivilegeEscalation: false resources: limits: cpu: "100m" memory: "128Mi" # RequiredTerapkan manifes
Sandbox:kubectl apply -f sandbox.yamlPastikan sandbox berjalan:
kubectl get sandbox
Memigrasikan Agent Sandbox di GKE dari v1alpha1 ke v1beta1
Jika cluster Anda di-deploy dengan versi Agent Sandbox di GKE yang lebih lama menggunakan resource kustom v1alpha1, Anda dapat mengupgrade ke GKE versi 1.36.3-gke.1767000 atau yang lebih baru dengan waktu nonaktif workload yang hampir nol.
Catatan: Prosedur migrasi ini berlaku untuk cluster yang menggunakan fitur Agent Sandbox di GKE terkelola (
--enable-agent-sandbox). Jika Anda men-deploy Agent Sandbox menggunakan manifes open source, lihat panduan migrasi upstream.
Perbedaan API utama antara v1alpha1 dan v1beta1
| Konsep | Perilaku v1alpha1 |
Perilaku v1beta1 |
Dampak migrasi |
|---|---|---|---|
| Target SandboxClaim | Mengizinkan referensi langsung ke SandboxTemplate tanpa warm pool (cold start). |
Memerlukan referensi ke SandboxWarmPool (spec.warmPoolRef.name). |
Klaim cold start harus dipetakan ke warm pool bayangan (replicas: 0). |
| Mode operasi sandbox | Disimpulkan dari kolom replika atau status. | Nilai eksplisit untuk kolom spec.operatingMode (seperti Running atau Suspended). |
Webhook konversi otomatis memetakan dan menetapkan kolom ini. |
| Versi penyimpanan CustomResourceDefinition | v1alpha1 disimpan di etcd (storage: true). |
v1beta1 disimpan di etcd (storage: true). |
Webhook dikonversi secara dinamis; langkah pasca-upgrade akan menyimpan ulang objek etcd. |
| Webhook konversi | Tidak ada. | Aktif di /convert (Port 9447). |
Konversi dua arah antara v1alpha1 dan v1beta1. |
Melakukan migrasi menggunakan alat migrasi
Untuk membuat warm pool bayangan dan menyimpan ulang penyimpanan persisten secara otomatis, gunakan skrip migrasi kanonis dari repositori Agent Sandbox.
Download dan siapkan skrip:
curl -LO https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/v0.5.6/helm/files/migrate.sh
chmod +x migrate.sh
Runbook migrasi langkah demi langkah
Untuk memigrasikan cluster yang ada dengan waktu nonaktif workload yang hampir nol, selesaikan tiga fase berikut secara berurutan:
Fase 1: Fase bootstrap pra-upgrade
Mencadangkan resource yang ada: Simpan cadangan YAML resource Agent Sandbox di GKE deklaratif Anda (
sandboxtemplates,sandboxwarmpools, dansandboxclaims):kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims \ --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yamlVerifikasi kepatuhan keamanan template: pastikan resource
SandboxTemplateyang ada memenuhi persyaratan deployment Agent Sandbox di GKE. Selama migrasi penyimpanan di Fase 3, pengontrol penerimaan akan menolak update ke template mana pun yang tidak mematuhi kebijakan keamanan ini.Pratinjau warm pool bayangan yang akan dibuat:
./migrate.sh --phase=bootstrap --dry-runJalankan fase bootstrap:
./migrate.sh --phase=bootstrapVerifikasi warm pool bayangan yang dibuat:
kubectl get sandboxwarmpools --all-namespaces \ -o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,REPLICAS:.spec.replicas,SHADOW:.metadata.annotations.agents\.x-k8s\.io/migration-shadow"
Fase 2: Mengupgrade bidang kontrol GKE
Upgrade bidang kontrol GKE ke versi 1.36.3-gke.1767000 atau yang lebih baru:
gcloud container clusters upgrade ${CLUSTER_NAME} \
--location=${LOCATION} \
--master \
--cluster-version=1.36.3-gke.1767000
Selama peluncuran bidang kontrol, perhatikan hal berikut:
- Pod tidak mengalami memulai ulang atau waktu nonaktif.
- Pengontrol baru dan endpoint webhook
/convertdi-deploy di bidang kontrol.
Fase 3: Migrasi penyimpanan pasca-upgrade
Setelah upgrade bidang kontrol selesai, muat ulang kredensial Anda dan tulis ulang objek etcd yang disimpan dengan menjalankan fase migrasi penyimpanan:
./migrate.sh --phase=migrate
Checklist verifikasi pasca-migrasi
| Item yang diperiksa | Perintah | Hasil yang diharapkan |
|---|---|---|
| Versi penyimpanan CustomResourceDefinition | kubectl get crd sandboxes.agents.x-k8s.io sandboxclaims.extensions.agents.x-k8s.io sandboxtemplates.extensions.agents.x-k8s.io sandboxwarmpools.extensions.agents.x-k8s.io -o jsonpath='{range .items[*]}{.metadata.name}{": storedVersions="}{.status.storedVersions}{"\n"}{end}' |
Semua 4 CustomResourceDefinition menampilkan:storedVersions=["v1beta1"] |
| Kontinuitas pod | kubectl get pods -n default -o wide |
Status: 1/1 RunningRestarts: 0(berlaku untuk cluster dengan sandbox yang berjalan aktif) |
| Pengikatan klaim | kubectl get sandboxclaims -n default -o yaml |
spec.warmPoolRef.name: shadow-pool-...status.conditions: Ready=True (memerlukan kepatuhan template terhadap persyaratan penerimaan) |
| Kompatibilitas v1alpha1 | kubectl get sandboxes.v1alpha1.agents.x-k8s.io |
Menampilkan peringatan penghentian dan menampilkan resource |
| CRUD native v1beta1 | kubectl apply -f sandbox-claim.yaml |
Berlaku dengan 0 peringatan |
Jika CustomResourceDefinition terus mencantumkan ["v1alpha1", "v1beta1"] di .status.storedVersions
setelah fase migrasi selesai, ini adalah perilaku Kubernetes yang diharapkan.
Skrip migrasi menulis ulang semua catatan yang ada ke v1beta1 di etcd, tetapi Kubernetes tidak otomatis menghapus versi yang tidak digunakan lagi dari daftar status.storedVersions.
Setelah mengonfirmasi bahwa semua resource dimigrasikan, Anda dapat secara opsional memangkas v1alpha1 dari versi yang disimpan:
for crd in \
sandboxes.agents.x-k8s.io \
sandboxclaims.extensions.agents.x-k8s.io \
sandboxtemplates.extensions.agents.x-k8s.io \
sandboxwarmpools.extensions.agents.x-k8s.io; do
kubectl patch crd "${crd}" --subresource=status --type=merge \
-p '{"status":{"storedVersions":["v1beta1"]}}'
done
Memecahkan masalah migrasi
Jika Anda mengalami masalah setelah mengupgrade bidang kontrol atau menjalankan migrasi penyimpanan, selesaikan masalah tersebut, bukan mencoba menurunkan versi bidang kontrol:
Klaim stuck di
WarmPoolNotFound:Jika klaim
v1alpha1cold start diupgrade tanpa menjalankan./migrate.sh --phase=bootstrap, buat warm pool bayangan yang hilang secara manual:apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxWarmPool metadata: name: shadow-pool-TEMPLATE_NAME namespace: NAMESPACE annotations: agents.x-k8s.io/migration-shadow: "true" spec: replicas: 0 sandboxTemplateRef: name: TEMPLATE_NAMEJika klaim bernama warm pool tertentu yang tidak ada lagi, buat resource
SandboxWarmPoolyang hilang dengan nama tersebut, atau updatespec.warmPoolRef.namepada klaim untuk mereferensikan warm pool yang ada.
Kondisi klaim
Ready=False: Jalankankubectl describe sandboxclaimuntuk memeriksa peristiwa pada klaim. PastikanSandboxTemplateyang direferensikan memenuhi semua persyaratan deployment Agent Sandbox di GKE, dan terapkan kembali template jika diperlukan.Error konversi atau pengontrol: Pastikan lease pemilihan pemimpin bidang kontrol aktif dengan menjalankan
kubectl get leases -n gke-managed-agentsandbox. Jika masalah berlanjut, hubungi Cloud Customer Care.
Menonaktifkan Agent Sandbox di GKE
Untuk menonaktifkan Agent Sandbox di GKE, gunakan perintah gcloud beta container clusters update dengan flag --no-enable-agent-sandbox.
gcloud beta container clusters update ${CLUSTER_NAME} \
--location=${LOCATION} \
--no-enable-agent-sandbox
Jika Anda membuat cluster Autopilot, lokasinya adalah region (misalnya, us-central1). Jika Anda membuat cluster Standar, lokasinya adalah zona (misalnya, us-central1-a).
Membersihkan resource
Untuk menghindari tagihan ke Google Cloud akun Anda, hapus cluster GKE yang Anda buat.
gcloud container clusters delete $CLUSTER_NAME \
--location=${LOCATION} \
--quiet
Jika Anda membuat cluster Autopilot, lokasinya adalah region (misalnya, us-central1). Jika Anda membuat cluster Standar, lokasinya adalah zona (misalnya, us-central1-a).
Langkah berikutnya
- Pelajari cara menyimpan dan memulihkan lingkungan Agent Sandbox di GKE dengan snapshot Pod.
- Pelajari teknologi dasar yang digunakan oleh Agent Sandbox di GKE.
- Pelajari keamanan GKE lebih lanjut .
- Pelajari project open source Agent Sandbox di GitHub.
- Pelajari cara menggunakan Kata Containers open source dengan Agent Sandbox di GKE. Kata Containers bukan Google Cloud 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.