Menyimpan dan memulihkan Agent Sandbox di lingkungan GKE dengan snapshot Pod

Dokumen ini menunjukkan cara menggunakan snapshot Pod GKE untuk menyimpan status lingkungan Agent Sandbox yang berjalan di GKE.

Agent Sandbox di GKE meningkatkan keamanan Anda dengan menyediakan lingkungan terisolasi untuk mengeksekusi kode yang tidak tepercaya, seperti kode yang dihasilkan oleh model bahasa besar (LLM). Menjalankan jenis kode ini secara langsung di cluster menimbulkan risiko keamanan, karena kode yang tidak tepercaya berpotensi mengakses atau mengganggu aplikasi lain atau node cluster yang mendasarinya.

Dengan snapshot Pod GKE, Anda dapat menyimpan dan memulihkan status lingkungan yang di-sandbox. Fungsi ini berguna karena alasan berikut:

  • Startup cepat: mengurangi waktu startup sandbox dengan memulihkan dari snapshot yang telah dihangatkan.
  • Agen yang berjalan lama: menjeda sandbox yang memerlukan waktu lama untuk dijalankan dan melanjutkannya nanti, atau memindahkannya ke node lain, tanpa kehilangan progres.
  • Workload stateful: mempertahankan konteks agen, seperti histori percakapan atau penghitungan sementara, dengan menyimpan dan memulihkan status lingkungan sandbox-nya.
  • Reproduksibilitas: menangkap status tertentu dan menggunakannya sebagai dasar untuk memulai beberapa sandbox baru dengan status inisialisasi yang sama.

Snapshot dapat dipicu dengan dua cara:

  • Pemicu manual: Anda membuat resource PodSnapshotManualTrigger untuk memicu snapshot.
  • Pemicu workload: aplikasi dalam sandbox itu sendiri memberi sinyal saat siap disimpan.

Dokumen ini menunjukkan cara memicu snapshot secara manual.

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

    • Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
    • 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. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

  3. Aktifkan Google Kubernetes Engine, Cloud Storage, Identity and Access Management (IAM) API, jika 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 Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Aktifkan API

  4. Di konsol Google Cloud , aktifkan Cloud Shell.

    Aktifkan Cloud Shell

Persyaratan

Snapshot Pod GKE memerlukan GKE versi 1.35.3-gke.1234000 atau yang lebih baru. Mode Autopilot dan Standard didukung.

Snapshot pod memerlukan gVisor dan tidak berfungsi dengan sandbox microVM.

Karena snapshot Pod memerlukan GKE Sandbox, lingkungan Anda tunduk pada batasan tertentu. Misalnya, snapshot Pod tidak mendukung jenis mesin E2. Oleh karena itu, tutorial ini membuat node pool yang terdiri dari mesin N2.

Untuk mengetahui daftar lengkap batasan, termasuk informasi tentang penggunaan jenis mesin berbasis GPU, lihat Batasan dan persyaratan.

Menentukan variabel lingkungan

Untuk menyederhanakan perintah yang Anda jalankan dalam dokumen ini, Anda dapat menetapkan variabel lingkungan di Cloud Shell. Variabel ini menyimpan nilai seperti ID project Google Cloud Anda, nama bucket Cloud Storage yang akan menyimpan snapshot, dan lokasi cluster GKE Anda.

Setelah menentukan variabel ini, Anda dapat menggunakannya kembali di beberapa perintah dengan mereferensikan nama variabel (misalnya, $CLUSTER_NAME), bukan mengetik ulang atau mengganti nilai setiap kali. Pendekatan ini membuat prosesnya lebih mudah diikuti dan mengurangi risiko error.

Untuk menentukan variabel lingkungan yang berguna berikut di Cloud Shell, jalankan perintah berikut:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export ZONE="us-central1-a"
export AGENT_SANDBOX_VERSION="v1.0.6"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="n2-standard-2"
export SNAPSHOTS_BUCKET_NAME="agent-sandbox-snapshots-${PROJECT_ID}"
export SNAPSHOT_NAMESPACE="pod-snapshots-ns"
export SNAPSHOT_KSA_NAME="pod-snapshot-sa"
export SNAPSHOT_FOLDER="my-snapshots"
export PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")

Berikut penjelasan tentang variabel lingkungan ini:

  • PROJECT_ID: ID project Google Cloud Anda saat ini. Perintah dalam dokumen ini menggunakan ID ini untuk memberi nama resource dan memberikan izin IAM.
  • CLUSTER_NAME: nama cluster GKE Anda (misalnya, agent-sandbox-cluster).
  • GKE_LOCATION: region Google Cloud untuk bucket Cloud Storage Anda (misalnya, us-central1). Jika Anda membuat cluster Autopilot, cluster tersebut juga akan menggunakan region ini.
  • ZONE: zona untuk cluster GKE Anda. Jika Anda membuat cluster Standard, tetapkan ini ke zona di region GKE_LOCATION (misalnya, us-central1-a). Untuk mengurangi biaya, dokumen ini membuat cluster Standard zona.
  • AGENT_SANDBOX_VERSION: versi pengontrol Agent Sandbox open source yang akan diinstal. Dokumen ini menggunakan versi 1.0.6.
  • NODE_POOL_NAME: nama node pool yang akan menjalankan workload dengan sandbox (misalnya, agent-sandbox-node-pool).
  • MACHINE_TYPE: jenis mesin node di node pool Anda (misalnya, n2-standard-2). Snapshot Pod tidak mendukung jenis mesin E2. Jika Anda ingin menggunakan jenis mesin berbasis GPU untuk node di node pool, lihat Batasan dan persyaratan. Untuk mengetahui detail tentang berbagai seri mesin dan memilih di antara berbagai opsi, lihat Panduan perbandingan dan resource kelompok mesin.
  • SNAPSHOTS_BUCKET_NAME: nama bucket Cloud Storage yang akan Anda buat untuk menyimpan snapshot.
  • SNAPSHOT_NAMESPACE: namespace Kubernetes tempat workload snapshot dan akun layanan Anda akan berada.
  • SNAPSHOT_KSA_NAME: nama akun layanan Kubernetes yang akan digunakan workload Anda untuk melakukan autentikasi.
  • SNAPSHOT_FOLDER: direktori di dalam bucket Cloud Storage tempat snapshot akan diatur.
  • PROJECT_NUMBER: ID numerik unik untuk project Anda, yang digunakan untuk binding izin IAM.

Ringkasan langkah-langkah konfigurasi

Untuk mengaktifkan snapshot Pod Agent Sandbox di lingkungan GKE, Anda perlu melakukan beberapa langkah konfigurasi. Untuk memahami langkah-langkah ini, sebaiknya pahami terlebih dahulu beberapa konsep utama, lalu proses snapshot:

Konsep utama

  • Lingkungan: aplikasi dalam sandbox berjalan di dalam Pod Kubernetes pada node cluster GKE.
  • Identitas: Pod dikaitkan dengan akun layanan Kubernetes dan berjalan di namespace khusus yang Anda buat. Bersama-sama, akun layanan Kubernetes dan namespace membentuk identitas unik yang digunakan untuk memberi Pod akses aman ke resource Google Cloud .
  • Izin: agar snapshot dapat disimpan ke Cloud Storage, identitas Pod harus diberi izin IAM tertentu yang memungkinkannya menulis ke bucket Cloud Storage.

Proses snapshot

  1. Pemicu: snapshot dimulai, baik secara manual (secara eksternal) maupun oleh workload yang di-sandbox itu sendiri. Dokumen ini menunjukkan pemicu manual yang Anda mulai dengan membuat resource PodSnapshotManualTrigger.
  2. Pengambilan: GKE mengambil status Pod yang sedang berjalan, seperti status memori Pod dan sistem filenya.
  3. Upload: menggunakan izin yang diberikan ke akun layanan Kubernetes Pod, GKE mengupload status yang diambil sebagai file snapshot ke bucket Cloud Storage yang ditentukan.

Untuk mempelajari lebih lanjut cara GKE menggunakan akun layanan Kubernetes dan peran IAM untuk mengakses resource Google Cloud , lihat Melakukan autentikasi ke APIGoogle Cloud dari workload GKE.

Untuk mengaktifkan snapshot Pod Agent Sandbox di lingkungan GKE, lakukan konfigurasi berikut. Pertama, Anda menyiapkan lingkungan cluster dengan membuat cluster GKE yang mengaktifkan Workload Identity Federation for GKE dan fitur snapshot Pod. Selanjutnya, Anda akan mengonfigurasi kebijakan Cloud Storage dan IAM untuk membantu memastikan snapshot Anda disimpan dengan aman dan sandbox Anda memiliki izin yang diperlukan. Terakhir, Anda membuat resource snapshot yang menentukan lokasi penyimpanan dan kebijakan untuk sandbox Anda.

Tabel berikut merangkum langkah-langkah konfigurasi yang perlu Anda lakukan, dan setiap langkah dijelaskan di bagian berikut:

Topik Tugas
Penyiapan cluster 1. Buat cluster GKE dan aktifkan fitur snapshot Pod dan Workload Identity Federation for GKE.
2. Men-deploy Agent Sandbox.
Mengonfigurasi penyimpanan dan izin 1. Buat bucket Cloud Storage dan folder terkelola.
2. Buat peran IAM khusus.
3. Buat namespace Kubernetes dan akun layanan Kubernetes (KSA).
4. Ikat peran IAM ke akun layanan Kubernetes.
5. Memberikan izin ke pengontrol snapshot.
Mengonfigurasi resource snapshot 1. Membuat resource PodSnapshotStorageConfig
2. Membuat resource PodSnapshotPolicy
3. Membuat resource SandboxTemplate, SandboxWarmPool, dan SandboxClaim

Penyiapan cluster

Aplikasi dengan sandbox berjalan di dalam Pod pada node cluster GKE, jadi Anda perlu menyiapkan lingkungan cluster. Bagian ini menunjukkan cara membuat cluster GKE, dan men-deploy pengontrol Agent Sandbox.

Membuat cluster GKE baru yang memenuhi persyaratan

Buat cluster GKE baru dengan snapshot Pod yang diaktifkan. Snapshot Pod memerlukan GKE versi 1.35.3-gke.1234000 atau yang lebih baru. Perintah berikut mendaftarkan cluster di saluran rilis Rapid, yang versi defaultnya memenuhi persyaratan ini:

Autopilot

Buat cluster Autopilot dengan fitur yang diperlukan:

gcloud container clusters create-auto ${CLUSTER_NAME} \
   --release-channel=rapid \
   --enable-pod-snapshots \
   --location=${GKE_LOCATION}

Standar

Buat cluster Standard dengan fitur yang diperlukan. Untuk mengurangi biaya, perintah berikut akan membuat cluster zona, yang menjalankan bidang kontrol dan nodenya di satu zona:

gcloud container clusters create ${CLUSTER_NAME} \
   --release-channel=rapid \
   --enable-pod-snapshots \
   --machine-type=${MACHINE_TYPE} \
   --workload-pool=${PROJECT_ID}.svc.id.goog \
   --workload-metadata=GKE_METADATA \
   --num-nodes=1 \
   --location=${ZONE}

Buat node pool dengan GKE Sandbox diaktifkan. GKE Sandbox adalah fitur keamanan container berdasarkan project gVisor open source yang menyediakan lapisan isolasi tambahan antara aplikasi yang berjalan dan sistem operasi host:

gcloud container node-pools create ${NODE_POOL_NAME} \
   --cluster ${CLUSTER_NAME} \
   --num-nodes=1 \
   --location=${ZONE} \
   --project=${PROJECT_ID} \
   --machine-type=${MACHINE_TYPE} \
   --sandbox type=gvisor

Mengambil kredensial

Ambil kredensial cluster agar kubectl CLI dapat terhubung ke cluster:

Autopilot 

gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

Standar 

gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${ZONE}

Men-deploy Agent Sandbox Controller ke cluster Anda

Anda dapat men-deploy pengontrol Agent Sandbox dan komponen yang diperlukan dengan menerapkan manifes rilis resmi ke cluster Anda. Manifes ini adalah file konfigurasi yang menginstruksikan Kubernetes untuk mendownload semua komponen yang diperlukan untuk men-deploy dan menjalankan pengontrol Agent Sandbox di cluster Anda.

Untuk men-deploy Agent Sandbox ke cluster GKE Anda, jalankan perintah berikut:

# Apply the release manifest for the controller and its CustomResourceDefinitions
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yaml

Untuk mengetahui informasi selengkapnya tentang cara menginstal Agent Sandbox, lihat Menginstal Agent Sandbox di GKE.

Memverifikasi pengontrol

Setelah menerapkan manifes, pastikan Pod pengontrol Agent Sandbox berjalan dengan benar di namespace agent-sandbox-system. Manifes secara otomatis membuat namespace agent-sandbox-system saat Anda menerapkannya pada langkah sebelumnya.

kubectl get pods -n agent-sandbox-system

Tunggu hingga Pod menampilkan 'Running' di kolom STATUS dan '1/1' di kolom READY. Jika Pod berjalan dengan benar, output-nya akan terlihat seperti ini:

NAME                                        READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-7d5c9b8f6d-x2k9p   1/1     Running   0          2m

Setelah berjalan, pengontrol Agent Sandbox dapat otomatis membuat dan mengelola lingkungan dengan sandbox untuk resource Sandbox apa pun yang Anda buat di cluster.

Mengonfigurasi penyimpanan dan izin

Bagian ini menunjukkan cara mengonfigurasi penyimpanan dan izin yang diperlukan untuk snapshot Pod. Anda membuat bucket Cloud Storage dan folder terkelola untuk menyimpan data snapshot. Kemudian, Anda memberikan izin yang diperlukan sandbox dan pengontrol snapshot untuk mengakses penyimpanan tersebut.

Membuat bucket Cloud Storage

Buat bucket untuk menyimpan snapshot Anda. Untuk membantu memastikan bahwa proses snapshot cepat dan hemat biaya, buat bucket dengan setelan berikut:

  • Enable hierarchical namespaces: fitur namespace hierarkis mengatur bucket Anda ke dalam hierarki sistem file, bukan namespace datar. Konfigurasi ini memungkinkan throughput baca dan tulis yang lebih tinggi, sehingga mempercepat penyimpanan dan pemulihan snapshot.
  • Nonaktifkan penghapusan sementara: fitur penghapusan sementara melindungi data dengan mempertahankan file yang dihapus selama jangka waktu tertentu. Namun, proses snapshot membuat dan menghapus banyak file sementara selama upload. Nonaktifkan penghapusan sementara untuk menghindari biaya yang tidak perlu untuk menyimpan file sementara ini.

Untuk membuat bucket dengan setelan ini, jalankan perintah berikut:

gcloud storage buckets create "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --uniform-bucket-level-access \
    --enable-hierarchical-namespace \
    --soft-delete-duration=0d \
    --location="${GKE_LOCATION}"

Membuat folder terkelola

Buat folder terkelola untuk mengatur snapshot dalam bucket Anda. Folder terkelola memungkinkan Anda menerapkan izin IAM ke folder tertentu, bukan ke seluruh bucket. Akses tingkat folder ini membatasi akses sandbox Anda hanya ke snapshot-nya sendiri, dan mengisolasi snapshot tersebut dari data lain dalam bucket.

Untuk membuat folder terkelola, jalankan perintah ini:

gcloud storage managed-folders create "gs://${SNAPSHOTS_BUCKET_NAME}/${SNAPSHOT_FOLDER}/"

Mengonfigurasi akun layanan dan peran IAM

Agar GKE dapat menyimpan snapshot dengan aman, akun layanan Kubernetes yang digunakan oleh Pod yang menjalankan workload dengan sandbox memerlukan izin untuk menulis ke bucket Anda. Anda memberikan izin ini dengan mengikat Google Cloud peran IAM ke akun layanan Kubernetes yang digunakan oleh Pod. Bagian ini menunjukkan cara membuat peran IAM kustom, membuat akun layanan Kubernetes, dan mengonfigurasi izin yang diperlukan.

  1. Buat peran IAM kustom bernama podSnapshotGcsReadWriter yang berisi izin yang diperlukan untuk menulis data snapshot. Jika peran ini sudah ada dalam project Anda, misalnya dari eksekusi dokumen ini sebelumnya, lewati langkah ini. Jika tidak, jalankan perintah berikut:

    gcloud iam roles create podSnapshotGcsReadWriter \
    --project="${PROJECT_ID}" \
    --permissions="storage.objects.get,storage.objects.create,storage.objects.delete,storage.folders.create"

    Jika peran berhasil dibuat, output-nya akan terlihat seperti ini:

    Created role [podSnapshotGcsReadWriter].
etag: BwZJUfjNbew=
includedPermissions:
- storage.folders.create
- storage.objects.create
- storage.objects.delete
- storage.objects.get
name: projects/${PROJECT_ID}/roles/podSnapshotGcsReadWriter
stage: ALPHA
title: podSnapshotGcsReadWriter

    Jika perintah gagal dengan error FAILED_PRECONDITION yang menyatakan bahwa ID peran telah ditandai untuk dihapus, berarti Anda baru saja menghapus peran dengan ID ini, misalnya dalam langkah-langkah pembersihan dari eksekusi dokumen ini sebelumnya. IAM tidak mengizinkan Anda menggunakan kembali ID tersebut hingga 37 hari. Jalankan perintah lagi dengan ID peran yang berbeda, seperti podSnapshotGcsReadWriter2, dan gunakan ID tersebut, bukan podSnapshotGcsReadWriter di bagian lain dokumen ini.

  2. Buat namespace tempat sandbox dan akun layanannya akan berada:

    kubectl create namespace "${SNAPSHOT_NAMESPACE}"

  3. Buat akun layanan Kubernetes di namespace yang baru saja Anda buat. Bersama-sama, akun layanan Kubernetes dan namespace membentuk identitas unik yang digunakan untuk memberikan akses aman sandbox Anda ke resource Google Cloud:

    kubectl create serviceaccount "${SNAPSHOT_KSA_NAME}" \
    --namespace "${SNAPSHOT_NAMESPACE}"

  4. Berikan peran roles/storage.bucketViewer ke semua akun layanan di namespace. Peran ini memungkinkan akun melihat metadata bucket, tetapi tidak untuk membaca atau menulis data itu sendiri:

    gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/namespace/${SNAPSHOT_NAMESPACE}" \
    --role="roles/storage.bucketViewer"

  5. Berikan peran podSnapshotGcsReadWriter kustom ke akun layanan Kubernetes untuk sandbox Anda. Binding ini hanya mengizinkan akun tertentu ini untuk menulis data ke folder terkelola. Perlu waktu beberapa menit agar peran khusus baru tersedia. Jadi, jika perintah ini gagal karena peran tidak ada, tunggu sebentar, lalu jalankan kembali perintah:

    gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/${SNAPSHOT_NAMESPACE}/sa/${SNAPSHOT_KSA_NAME}" \
    --role="projects/${PROJECT_ID}/roles/podSnapshotGcsReadWriter"

  6. Berikan peran roles/storage.objectUser ke akun layanan Kubernetes. Peran ini diperlukan agar agen snapshot Pod dapat melakukan operasi pada folder terkelola:

    gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/${SNAPSHOT_NAMESPACE}/sa/${SNAPSHOT_KSA_NAME}" \
    --role="roles/storage.objectUser"

Memberikan izin ke pengontrol snapshot

Berikan peran objectUser ke pengontrol snapshot sistem GKE. Izin ini memungkinkan pengontrol mengelola siklus proses snapshot, seperti menghapus objek snapshot saat Anda menghapus resource PodSnapshot:

gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --member="serviceAccount:service-${PROJECT_NUMBER}@container-engine-robot.iam.gserviceaccount.com" \
    --role="roles/storage.objectUser"

Mengonfigurasi resource snapshot

Bagian ini menunjukkan cara mengonfigurasi resource snapshot untuk workload Agent Sandbox di GKE.

Menentukan penyimpanan dan aturan snapshot

Untuk menentukan tempat GKE menyimpan snapshot Anda dan aturan yang mengatur proses snapshot, Anda membuat dua resource kustom:

  • PodSnapshotStorageConfig: resource ini menentukan lokasi bucket dan folder Cloud Storage tempat GKE menyimpan file snapshot Anda.
  • PodSnapshotPolicy: resource ini menentukan Pod mana yang memenuhi syarat untuk snapshot berdasarkan label Kubernetes-nya. Aturan ini juga menentukan aturan pemicu, seperti apakah snapshot bersifat manual atau dimulai oleh workload sandbox. Contoh ini mengelompokkan snapshot berdasarkan label agents.x-k8s.io/sandbox-name-hash, yang ditambahkan oleh pengontrol Agent Sandbox ke Pod setiap sandbox. Pengelompokan ini berarti GKE memulihkan setiap sandbox hanya dari snapshot-nya sendiri.

Untuk menerapkan kedua resource dalam satu langkah, jalankan perintah berikut di Cloud Shell. Metode ini membantu memastikan bahwa variabel lingkungan Anda diinjeksikan dengan benar:

kubectl apply -f - <<EOF
apiVersion: podsnapshot.gke.io/v1
kind: PodSnapshotStorageConfig
metadata:
  name: cpu-pssc-gcs
spec:
  snapshotStorageConfig:
    gcs:
      bucket: "${SNAPSHOTS_BUCKET_NAME}"
      path: "${SNAPSHOT_FOLDER}"
EOF

sleep 5

kubectl apply -f - <<EOF
apiVersion: podsnapshot.gke.io/v1
kind: PodSnapshotPolicy
metadata:
  name: cpu-psp
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  storageConfigName: cpu-pssc-gcs
  selector:
    matchLabels:
      app: agent-sandbox-workload
  triggerConfig:
    type: manual
    postCheckpoint: resume
  snapshotGroupingRules:
    groupByLabelValue:
      labels:
      - agents.x-k8s.io/sandbox-name-hash
EOF

Memverifikasi konfigurasi

Setelah Anda menerapkan konfigurasi dan kebijakan penyimpanan snapshot, pastikan resource siap digunakan. Bagian ini menunjukkan cara memeriksa status resource kustom ini.

  1. Periksa status resource PodSnapshotStorageConfig:

    kubectl get podsnapshotstorageconfigs.podsnapshot.gke.io cpu-pssc-gcs -o yaml

    Output harus berisi kondisi dengan type: Ready dan status: "True":

    status:
  conditions:
  - lastTransitionTime: "2025-10-31T18:18:02Z"
    message: Valid PodSnapshotStorageConfig
    reason: StorageConfigValid
    status: "True"
    type: Ready

  2. Periksa status resource PodSnapshotPolicy:

    kubectl get podsnapshotpolicies.podsnapshot.gke.io cpu-psp \
  --namespace "${SNAPSHOT_NAMESPACE}" -o yaml

    Output harus berisi kondisi dengan type: Ready dan status: "True". Output ini juga akan menunjukkan bahwa resource PodSnapshotStorageConfig yang direferensikan telah ditemukan:

    status:
  conditions:
  - lastTransitionTime: "2025-10-31T18:19:47Z"
    message: The referenced PodSnapshotStorageConfig "cpu-pssc-gcs" was found
    reason: StorageConfigValid
    status: "True"
    type: Ready

Membuat template sandbox

Setelah kebijakan dan izin penyimpanan diterapkan, buat resource SandboxTemplate, SandboxWarmPool, dan SandboxClaim. Resource SandboxWarmPool membuat sandbox yang telah di-pre-warm tetap berjalan, dan resource SandboxClaim mengklaim sandbox tersebut dari pool. Agar proses snapshot berfungsi, sandbox harus berjalan dengan akun layanan Kubernetes yang Anda buat sebelumnya dalam dokumen ini. Sandbox juga harus memiliki label yang Anda tentukan sebelumnya di resource PodSnapshotPolicy.

Contoh ini menggunakan aplikasi Python yang mencetak penghitung inkremental ke log. Penghitung ini memungkinkan Anda memverifikasi bahwa status berhasil disimpan dan dipulihkan nanti.

Autopilot

Snapshot pod tidak mendukung jenis mesin E2. Di Autopilot, GKE mungkin secara default menggunakan jenis mesin yang tidak mendukung snapshot Pod. Untuk membantu memastikan workload Anda berjalan di hardware yang kompatibel, Anda harus menggunakan ComputeClass kustom untuk memprioritaskan kelompok mesin yang kompatibel.

  1. Simpan manifes berikut sebagai non-e2-class.yaml:

    apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: non-e2-class
spec:
  priorities:
  - machineFamily: n2
  - machineFamily: c3
  activeMigration:
    optimizeRulePriority: false
  whenUnsatisfiable: DoNotScaleUp

  2. Terapkan manifes:

    kubectl apply -f non-e2-class.yaml

  3. Untuk membuat resource SandboxTemplate dan SandboxWarmPool, terapkan manifes berikut. Perhatikan bahwa resource SandboxTemplate merujuk ke ComputeClass yang baru saja Anda buat menggunakan pemilih node cloud.google.com/compute-class: non-e2-class.

    kubectl apply -f - <<EOF
---
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  podTemplate:
    metadata:
      labels:
        app: agent-sandbox-workload
    spec:
      serviceAccountName: ${SNAPSHOT_KSA_NAME}
      runtimeClassName: gvisor
      nodeSelector:
        cloud.google.com/compute-class: non-e2-class
      containers:
      - name: my-container
        image: python:3.10-slim
        command: ["python3", "-c"]
        args:
          - |
            import time
            i = 0
            while True:
              print(f"Count: {i}", flush=True)
              i += 1
              time.sleep(1)
---
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  replicas: 1
  sandboxTemplateRef:
    name: python-runtime-template
EOF

Standar

Untuk membuat resource SandboxTemplate dan SandboxWarmPool, terapkan manifes berikut:

kubectl apply -f - <<EOF
---
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  podTemplate:
    metadata:
      labels:
        app: agent-sandbox-workload
    spec:
      serviceAccountName: ${SNAPSHOT_KSA_NAME}
      runtimeClassName: gvisor
      containers:
      - name: my-container
        image: python:3.10-slim
        command: ["python3", "-c"]
        args:
          - |
            import time
            i = 0
            while True:
              print(f"Count: {i}", flush=True)
              i += 1
              time.sleep(1)
---
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  replicas: 1
  sandboxTemplateRef:
    name: python-runtime-template
EOF

Setelah Anda membuat resource, klaim sandbox dari warm pool:

  1. Tunggu hingga sandbox warm pool siap:

    kubectl wait sandboxwarmpool python-sandbox-warmpool \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  --for=jsonpath='{.status.readyReplicas}'=1 \
  --timeout=600s

  2. Buat resource SandboxClaim yang mengklaim sandbox dari warm pool:

    kubectl apply -f - <<EOF
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxClaim
metadata:
  name: python-sandbox-example
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  warmPoolRef:
    name: python-sandbox-warmpool
EOF

  3. Tunggu hingga klaim siap, lalu simpan nama sandbox yang digunakan klaim. Pod sandbox memiliki nama yang sama dengan sandbox:

    kubectl wait sandboxclaim python-sandbox-example \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  --for=condition=Ready \
  --timeout=300s

export SANDBOX_NAME=$(kubectl get sandboxclaim python-sandbox-example \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  -o jsonpath='{.status.sandbox.name}')
echo "${SANDBOX_NAME}"

Sandbox Anda kini berjalan dengan identitas yang benar dan siap untuk diambil snapshot-nya.

Membuat snapshot

Bagian ini menunjukkan cara memicu snapshot sandbox yang sedang berjalan secara manual. Anda membuat resource pemicu yang menargetkan Pod sandbox, lalu memverifikasi bahwa proses snapshot berhasil diselesaikan.

  1. Periksa log penghitung awal: Sebelum memicu snapshot, lihat log sandbox yang sedang berjalan untuk melihat nilai penghitung saat ini. Melihat log akan menetapkan dasar pengukuran untuk dibandingkan setelah pemulihan.

    kubectl logs "${SANDBOX_NAME}" --namespace "${SNAPSHOT_NAMESPACE}" --tail=5

    Output akan menampilkan beberapa baris terakhir penghitung, misalnya:

    Count: 15
Count: 16
Count: 17

    Perhatikan beberapa nilai "Count" terakhir yang dicetak.

  2. Buat resource PodSnapshotManualTrigger: Mulai snapshot:

    kubectl apply -f - <<EOF
apiVersion: podsnapshot.gke.io/v1
kind: PodSnapshotManualTrigger
metadata:
  name: cpu-snapshot-trigger
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  targetPod: ${SANDBOX_NAME}
EOF

  3. Pastikan pemicu manual berhasil:

    kubectl get podsnapshotmanualtriggers.podsnapshot.gke.io \
  --namespace "${SNAPSHOT_NAMESPACE}"

    Output akan menampilkan status Complete, yang menunjukkan bahwa GKE berhasil memicu snapshot Pod target:

    NAME                   TARGET POD                      STATUS     AGE
cpu-snapshot-trigger   python-sandbox-warmpool-x7k2p   Complete   XXs

  4. Lihat detail selengkapnya tentang status yang diambil dengan mendeskripsikan pemicu:

    kubectl describe podsnapshotmanualtriggers.podsnapshot.gke.io cpu-snapshot-trigger \
  --namespace "${SNAPSHOT_NAMESPACE}"

    Output-nya berisi bagian Snapshot Created dengan nama unik file snapshot yang disimpan di bucket Anda:

    Status:
  Conditions:
    Last Transition Time:  2026-01-30T19:11:04Z
    Message:               checkpoint completed successfully
    Reason:                Complete
    Status:                True
    Type:                  Triggered
  Observed Generation:     1
  Snapshot Created:
    Name:  <UNIQUE_SNAPSHOT_NAME>

Memulihkan dari snapshot

Setelah mengambil snapshot, Anda dapat menangguhkan sandbox untuk mengosongkan resource komputasinya, dan nanti melanjutkan sandbox dari status tersimpannya. Saat Anda menangguhkan sandbox, pengontrol Agent Sandbox akan menghapus Pod sandbox, tetapi mempertahankan resource Sandbox. Saat Anda melanjutkan sandbox, pengontrol akan membuat ulang Pod, dan pengontrol snapshot Pod akan otomatis memulihkan Pod dari snapshot terbaru sandbox tersebut.

  1. Tunggu hingga snapshot siap. GKE hanya memulihkan Pod dari snapshot yang sudah siap. Jika Anda menangguhkan sandbox sebelum snapshot siap, sandbox akan dimulai tanpa status tersimpan saat Anda melanjutkannya.

    export SNAPSHOT_NAME=$(kubectl get podsnapshotmanualtriggers.podsnapshot.gke.io cpu-snapshot-trigger \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  -o jsonpath='{.status.snapshotCreated.name}')

kubectl wait podsnapshots.podsnapshot.gke.io "${SNAPSHOT_NAME}" \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  --for=condition=Ready \
  --timeout=600s

  2. Untuk menangguhkan sandbox, tetapkan kolom operatingMode ke Suspended, lalu tunggu hingga pengontrol menghapus Pod sandbox:

    kubectl patch sandbox "${SANDBOX_NAME}" \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  --type=merge \
  -p '{"spec":{"operatingMode":"Suspended"}}'

kubectl wait pod "${SANDBOX_NAME}" \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  --for=delete \
  --timeout=120s

  3. Untuk melanjutkan sandbox, tetapkan kolom operatingMode ke Running, lalu tunggu hingga sandbox siap:

    kubectl patch sandbox "${SANDBOX_NAME}" \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  --type=merge \
  -p '{"spec":{"operatingMode":"Running"}}'

kubectl wait sandbox "${SANDBOX_NAME}" \
  --namespace "${SNAPSHOT_NAMESPACE}" \
  --for=condition=Ready \
  --timeout=300s

  4. Pastikan pemulihan telah dilakukan dengan melihat log. Perhatikan bahwa penghitung berlanjut dari titik pengambilan snapshot:

    kubectl logs "${SANDBOX_NAME}" --namespace "${SNAPSHOT_NAMESPACE}"

    Output akan menampilkan penghitung yang melanjutkan, misalnya:

    Count: 18
Count: 19
Count: 20
Count: 21

    Jika penghitung dimulai dari 0, Pod akan dimulai tanpa memulihkan dari snapshot.

Membersihkan resource

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan dalam dokumen ini, lakukan langkah-langkah berikut untuk menghapus resource yang Anda buat:

  1. Hapus klaim sandbox dan warm pool untuk menghentikan Pod yang sedang berjalan dan mengizinkan pengontrol Agent Sandbox menghentikan container dengan baik.

    kubectl delete sandboxclaims --all --namespace "${SNAPSHOT_NAMESPACE}"
kubectl delete sandboxwarmpools --all --namespace "${SNAPSHOT_NAMESPACE}"

  2. Hapus template sandbox dan pemicu manual yang digunakan untuk membuat sandbox dan memulai snapshot.

    # Delete the blueprints
kubectl delete sandboxtemplates --all --namespace "${SNAPSHOT_NAMESPACE}"

# Delete the snapshot initiation objects
kubectl delete podsnapshotmanualtriggers --all --namespace "${SNAPSHOT_NAMESPACE}"

  3. Hapus kebijakan snapshot yang menentukan Pod mana yang memenuhi syarat untuk snapshot dalam namespace Anda.

    kubectl delete podsnapshotpolicy cpu-psp --namespace "${SNAPSHOT_NAMESPACE}"

  4. Hapus konfigurasi penyimpanan snapshot, yang merupakan definisi global backend penyimpanan snapshot Anda. Karena resource ini tercakup dalam cluster, jangan gunakan flag namespace.

    kubectl delete podsnapshotstorageconfig cpu-pssc-gcs

  5. Jika Anda membuatnya untuk Autopilot, hapus ComputeClass.

    kubectl delete computeclass non-e2-class

  6. Hapus namespace Kubernetes untuk otomatis menghapus akun layanan Kubernetes dan metadata dengan namespace yang tersisa.

    kubectl delete namespace "${SNAPSHOT_NAMESPACE}"

  7. Hapus cluster GKE untuk menghapus infrastruktur yang mendasarinya dan semua node yang terkait dengan tutorial.

    Autopilot 

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

    Standar 

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

  8. Hapus bucket Cloud Storage (opsional) menggunakan perintah penghapusan rekursif jika Anda ingin mereset penyimpanan sepenuhnya. Perhatikan bahwa Anda dapat melewati langkah ini jika ingin menggunakan kembali bucket yang dikonfigurasi dengan benar untuk pengujian mendatang.

    gcloud storage rm --recursive "gs://${SNAPSHOTS_BUCKET_NAME:?Error: SNAPSHOTS_BUCKET_NAME is not set. Please re-define the environment variables you defined earlier.}"

  9. Hapus peran IAM kustom (opsional) jika Anda ingin mengembalikan project ke status yang benar-benar bersih. Karena peran IAM tetap ada bahkan setelah cluster dihapus, Anda harus menghapusnya secara terpisah.

    gcloud iam roles delete podSnapshotGcsReadWriter --project="${PROJECT_ID}"

Langkah berikutnya