Mengaktifkan Sandbox Agen di GKE

Dokumen ini menjelaskan cara mengaktifkan fitur Sandbox Agen di cluster Google Kubernetes Engine (GKE). Dokumen ini juga menjelaskan cara membuat lingkungan sandbox di cluster untuk mengeksekusi kode yang tidak tepercaya dengan aman.

Untuk mengetahui ringkasan 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.

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 Project Creator (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 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.

    Aktifkan API

  4. Di konsol Google Cloud , aktifkan Cloud Shell.

    Aktifkan Cloud Shell

  5. Pastikan cluster Anda menjalankan GKE versi 1.36.3-gke.1767000 atau yang lebih baru (mendukung v1beta1 API).

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 variabel lingkungan ini:

  • PROJECT_ID: ID project Google Cloud 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.
  • LOCATION: Google Cloud region atau zona tempat cluster GKE Anda dibuat. Tetapkan ini ke region (misalnya, us-central1) jika Anda membuat cluster Autopilot, atau zona (misalnya, us-central1-a) jika Anda membuat cluster Standard.
  • CLUSTER_VERSION: versi GKE yang akan dijalankan cluster Anda (1.36.3-gke.1767000 atau yang lebih baru).
  • NODE_POOL_NAME: nama node pool yang akan menjalankan beban kerja sandbox—misalnya, agent-sandbox-pool. Variabel ini hanya diperlukan jika Anda membuat cluster GKE Standard.
  • 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. Variabel ini hanya diperlukan jika Anda membuat cluster GKE Standard.

Mengaktifkan Sandbox Agen

Anda dapat mengaktifkan fitur Agent Sandbox saat membuat cluster baru, atau saat memperbarui cluster yang sudah ada.

Mengaktifkan Agent Sandbox saat membuat cluster GKE baru

Sebaiknya gunakan cluster Autopilot untuk pengalaman Kubernetes yang terkelola sepenuhnya. Untuk memilih mode operasi GKE yang paling sesuai untuk workload Anda, lihat Memilih mode operasi GKE.

Autopilot

Untuk membuat cluster Autopilot GKE baru dengan Agent Sandbox 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 Standard baru dengan Agent Sandbox yang diaktifkan, Anda harus membuat cluster, menambahkan node pool dengan gVisor yang diaktifkan, lalu mengaktifkan fitur Agent Sandbox. Untuk menghemat biaya, sebaiknya buat cluster zonal dengan satu node per pool:

  1. Membuat cluster:

    gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --cluster-version=${CLUSTER_VERSION}

    Untuk cluster Standar ini, pastikan variabel lingkungan LOCATION disetel ke zona (misalnya, us-central1-a).

  2. 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=gvisor

    LOCATION harus berupa zona yang sama dengan yang Anda gunakan saat membuat cluster.

  3. Perbarui cluster untuk mengaktifkan fitur Sandbox Agen:

    gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --enable-agent-sandbox

Mengaktifkan Agent Sandbox saat mengupdate cluster GKE yang ada

Untuk mengaktifkan Agent Sandbox di 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 disetel ke region atau zona tempat cluster yang ada berada.

  1. Jika Anda menggunakan cluster GKE Standard, Agent Sandbox mengandalkan gVisor. Jika cluster Standard Anda tidak memiliki node pool yang kompatibel dengan 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=gvisor

  2. Perbarui cluster untuk mengaktifkan fitur Sandbox Agen:

    gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --enable-agent-sandbox

Memverifikasi konfigurasi

Anda dapat memverifikasi apakah fitur Sandbox Agen diaktifkan dengan memeriksa deskripsi cluster.

gcloud beta container clusters describe ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --format="value(addonsConfig.agentSandboxConfig.enabled)"

Jika Anda membuat cluster Autopilot, lokasi adalah region (misalnya, us-central1). Jika Anda membuat cluster Standard, lokasi adalah zona (misalnya, us-central1-a).

Jika fitur berhasil diaktifkan, perintah akan menampilkan True.

Persyaratan deployment Sandbox Agen

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 Izin Memvalidasi (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 menargetkan sandbox.gke.io/runtime: gvisor.
  • tolerations: harus menyertakan toleransi untuk taint sandbox.gke.io/runtime=gvisor:NoSchedule.

Konfigurasi yang dilarang

Manifes deployment Anda tidak boleh menyertakan salah satu hal berikut:

  • hostNetwork: true, hostPID: true, atau hostIPC: true.
  • privileged: true dalam konteks keamanan container.
  • HostPath volume.
  • Menambahkan kemampuan (capabilities.add).
  • Setelan hostPort.
  • Sysctl kustom.
  • Volume yang diproyeksikan untuk token atau sertifikat akun layanan.

Men-deploy lingkungan dalam sandbox

Sebaiknya deploy lingkungan sandbox dengan menentukan SandboxTemplate dan memastikan instance yang sudah di-warm-up siap menggunakan SandboxWarmPool. Kemudian, Anda dapat meminta instance dari node pool yang sudah di-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.

SandboxTemplate berfungsi sebagai cetak biru yang dapat digunakan kembali. SandboxWarmPool membantu memastikan sejumlah Pod yang telah di-warm up selalu berjalan dan siap untuk diklaim. Penggunaan resource kustom ini meminimalkan latensi startup.

Untuk men-deploy lingkungan sandbox dengan membuat SandboxTemplate dan SandboxWarmPool, selesaikan langkah-langkah berikut:

  1. Di Cloud Shell, buat file bernama sandbox-template.yaml dengan 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: OnFailure

  2. Terapkan manifes SandboxTemplate:

    kubectl apply -f sandbox-template.yaml

  3. Buat file bernama sandbox-warmpool.yaml dengan 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-template

  4. Terapkan manifes SandboxWarmPool:

    kubectl apply -f sandbox-warmpool.yaml

Membuat SandboxClaim

SandboxClaim meminta sandbox dari kumpulan siap pakai. Karena Anda membuat pool hangat, 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:

  1. Buat file bernama sandbox-claim.yaml dengan 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-warmpool

  2. Terapkan manifes SandboxClaim:

    kubectl apply -f sandbox-claim.yaml

  3. Pastikan sandbox, klaim, dan warm pool sudah siap:

    kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod

Alternatif: Membuat Sandbox secara langsung

Jika tidak memerlukan waktu mulai yang cepat yang disediakan oleh kumpulan siap pakai, Anda dapat men-deploy Sandbox secara langsung tanpa menggunakan template.

Untuk men-deploy lingkungan sandbox dengan membuat Sandbox secara langsung, selesaikan langkah-langkah berikut:

  1. Buat file bernama sandbox.yaml dengan 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" # Required

  2. Terapkan manifes Sandbox:

    kubectl apply -f sandbox.yaml

  3. Pastikan sandbox sedang berjalan:

    kubectl get sandbox

Memigrasikan Sandbox Agen dari v1alpha1 ke v1beta1

Jika cluster Anda di-deploy dengan Agent Sandbox versi yang lebih lama menggunakan resource kustom v1alpha1, Anda dapat mengupgrade ke GKE versi 1.36.3-gke.1767000 atau yang lebih baru dengan downtime workload yang hampir nol.

Catatan: Prosedur migrasi ini berlaku untuk cluster yang menggunakan fitur Managed GKE Agent Sandbox (--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 Memungkinkan referensi langsung ke SandboxTemplate tanpa warm pool (cold start). Memerlukan referensi ke SandboxWarmPool (spec.warmPoolRef.name). Klaim cold start harus dipetakan ke shadow warm pool (replicas: 0).
Mode operasi sandbox Disimpulkan dari replika atau kolom status. Nilai eksplisit untuk kolom spec.operatingMode (seperti Running atau Paused). Webhook konversi otomatis memetakan dan menyetel kolom ini.
Versi penyimpanan CRD v1alpha1 yang disimpan di etcd (storage: true). v1beta1 yang disimpan di etcd (storage: true). Webhook dikonversi secara dinamis; langkah pasca-upgrade mempertahankan kembali 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 shadow warm pool dan menyimpan ulang penyimpanan 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

Buku panduan migrasi langkah demi langkah

Untuk memigrasikan cluster yang ada dengan periode nonaktif workload mendekati nol, selesaikan tiga fase berikut secara berurutan:

Fase 1: Fase bootstrap pra-upgrade

  1. Mencadangkan resource yang ada: Simpan cadangan YAML semua resource kustom Agent Sandbox di cluster Anda:

    kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims,sandboxes \
    --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yaml

  2. Verifikasi kepatuhan keamanan template: pastikan resource yang ada memenuhi SandboxTemplate persyaratan deployment Agent Sandbox. Selama migrasi penyimpanan di Fase 3, pengontrol penerimaan menolak pembaruan pada template yang tidak mematuhi kebijakan keamanan ini.

  3. Pratinjau kumpulan bayangan yang akan dibuat:

    ./migrate.sh --phase=bootstrap --dry-run

  4. Jalankan fase bootstrap:

    ./migrate.sh --phase=bootstrap

  5. Verifikasi kumpulan 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 mulai ulang atau periode nonaktif.
  • Endpoint webhook /convert dan pengontrol baru di-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 pascamigrasi

Centang item Perintah Hasil yang diharapkan
Versi penyimpanan CRD 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 CRD ditampilkan:
storedVersions=["v1beta1"]
Kontinuitas pod kubectl get pods -n default -o wide Status: 1/1 Running
Restarts: 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 penggunaan dan menampilkan resource
CRUD native v1beta1 kubectl apply -f sandbox-claim.yaml Berlaku dengan 0 peringatan

Menonaktifkan Sandbox Agen

Untuk menonaktifkan fitur Sandbox Agen, 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, lokasi adalah region (misalnya, us-central1). Jika Anda membuat cluster Standard, lokasi adalah zona (misalnya, us-central1-a).

Membersihkan resource

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

gcloud container clusters delete $CLUSTER_NAME \
    --location=${LOCATION} \
    --quiet

Jika Anda membuat cluster Autopilot, lokasi adalah region (misalnya, us-central1). Jika Anda membuat cluster Standard, lokasi adalah zona (misalnya, us-central1-a).

Langkah berikutnya