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 secara 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 peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. 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.35.2-gke.1269000 atau yang lebih baru.

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.35.2-gke.1269000"
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. Fitur Sandbox Agen memerlukan versi 1.35.2-gke.1269000 atau yang lebih baru.
  • NODE_POOL_NAME: nama node pool yang akan menjalankan workload dengan 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.35.2-gke.1269000 atau yang lebih baru.

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 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/v1alpha1
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/v1alpha1
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 template. Karena Anda membuat pool hangat, Sandbox yang dibuat akan menggunakan Pod yang berjalan dari pool, bukan memulai Pod baru.

Untuk meminta sandbox dari template dengan membuat SandboxClaim, selesaikan langkah-langkah berikut:

  1. Buat file bernama sandbox-claim.yaml dengan konten berikut:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: sandbox-claim
  namespace: default
spec:
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

  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: Buat 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/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-example-2
spec:
  replicas: 1
  podTemplate:
    metadata:
      labels:
        sandbox: sandbox-example
    spec:
      runtimeClassName: gvisor
      restartPolicy: Always
      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

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