Mengaktifkan Sandbox Agen di GKE

Dokumen ini menjelaskan cara mengaktifkan fitur Agent Sandbox di cluster Google Kubernetes Engine (GKE). Dokumen ini juga menjelaskan cara membuat lingkungan sandbox di cluster untuk menjalankan kode yang tidak tepercaya dengan 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.

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.

    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 Google Cloud konsol, 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 Anda saat ini. Google Cloud 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 dibuat. Google Cloud 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. Fitur Agent Sandbox memerlukan versi 1.35.2-gke.1269000 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

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 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 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 yang diaktifkan, Anda harus membuat cluster, menambahkan node pool dengan gVisor yang diaktifkan, lalu mengaktifkan fitur Agent Sandbox. Untuk menghemat biaya, sebaiknya buat cluster zona 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 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. Perbarui cluster untuk mengaktifkan fitur Agent Sandbox:

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

Mengaktifkan Agent Sandbox saat memperbarui cluster GKE yang sudah ada

Untuk mengaktifkan Agent Sandbox di cluster yang sudah ada, cluster harus menjalankan versi 1.35.2-gke.1269000 atau yang lebih baru.

Pastikan variabel lingkungan LOCATION Anda ditetapkan ke region atau zona tempat cluster yang sudah ada berada.

  1. Jika Anda menggunakan cluster GKE Standar, Agent Sandbox 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. Perbarui cluster untuk mengaktifkan fitur Agent Sandbox:

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

Memverifikasi konfigurasi

Anda dapat memverifikasi apakah fitur Agent Sandbox 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

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 yang sudah di-warm up 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 pelanggan 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 warm pool, Sandbox yang dibuat akan mengadopsi 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: 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/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 Agent Sandbox

Untuk menonaktifkan fitur Agent Sandbox, 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