Mengaktifkan Sandbox Agen di GKE

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

  1. 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 izin resourcemanager.projects.create. Pelajari cara memberikan peran.

    Buka pemilih project

  2. Pastikan penagihan diaktifkan untuk Google Cloud project Anda.

  3. 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.

    Aktifkan API

  4. Di Google Cloud konsol, 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 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.1767000 atau 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:

  1. 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 LOCATION ditetapkan 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 merupakan zona yang sama dengan yang Anda gunakan saat membuat cluster.

  3. 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.

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

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:

  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 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:

  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 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:

  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 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

  1. Mencadangkan resource yang ada: Simpan cadangan YAML resource Agent Sandbox di GKE deklaratif Anda (sandboxtemplates, sandboxwarmpools, dan sandboxclaims):

    kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims \
        --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yaml
    
  2. Verifikasi kepatuhan keamanan template: pastikan resource SandboxTemplate yang 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.

  3. Pratinjau warm pool bayangan yang akan dibuat:

    ./migrate.sh --phase=bootstrap --dry-run
    
  4. Jalankan fase bootstrap:

    ./migrate.sh --phase=bootstrap
    
  5. Verifikasi 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 /convert 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 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 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 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 v1alpha1 cold 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_NAME
      
    • Jika klaim bernama warm pool tertentu yang tidak ada lagi, buat resource SandboxWarmPool yang hilang dengan nama tersebut, atau update spec.warmPoolRef.name pada klaim untuk mereferensikan warm pool yang ada.

  • Kondisi klaim Ready=False: Jalankan kubectl describe sandboxclaim untuk memeriksa peristiwa pada klaim. Pastikan SandboxTemplate yang 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