Menyimpan dan memulihkan lingkungan Sandbox Agen dengan snapshot Pod

Dokumen ini hanya ditujukan untuk cluster Standard.

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

Sandbox Agen menyediakan lingkungan yang aman dan 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.

Snapshot Pod GKE memungkinkan Anda menyimpan dan memulihkan status lingkungan sandbox. Fungsi ini berguna karena alasan berikut:

  • Startup cepat: mengurangi waktu mulai sandbox dengan memulihkan dari snapshot yang telah dipanaskan sebelumnya.
  • Agen yang berjalan lama: jeda sandbox yang membutuhkan waktu lama untuk dijalankan dan lanjutkan nanti, atau pindahkan ke node lain, tanpa kehilangan progres.
  • Workload stateful: mempertahankan konteks agen, seperti histori percakapan atau penghitungan perantara, dengan menyimpan dan memulihkan status lingkungan sandbox-nya.
  • Reproduksibilitas: merekam status tertentu dan menggunakannya sebagai dasar untuk memulai beberapa sandbox baru dengan status yang sama.

Snapshot dapat dipicu dengan dua cara:

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

Dokumen ini menunjukkan cara memicu snapshot secara manual.

Catatan: Snapshot Pod GKE adalah fitur Pratinjau.

Sebelum memulai

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Google Kubernetes Engine, Cloud Storage, Identity and Access Management (IAM) APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    Persyaratan

    Untuk menggunakan snapshot Pod GKE, Anda memerlukan cluster mode Standar yang menjalankan GKE versi 1.34.1-gke.3084001 atau yang lebih baru. Sebaiknya Anda menggunakan GKE versi 1.35 atau yang lebih baru. GKE versi 1.34 memiliki masalah umum yang menyebabkan pembuatan titik pemeriksaan dapat gagal dengan error input/output yang terkait dengan bug izin Cloud Storage.

    Snapshot pod tidak mendukung jenis mesin E2. Oleh karena itu, tutorial ini membuat node pool yang terdiri dari mesin N2.

    Jika Anda ingin menggunakan jenis mesin berbasis GPU untuk node di node pool, 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 , nama bucket Cloud Storage yang akan menyimpan snapshot, dan lokasi cluster GKE.

    Setelah menentukan variabel ini, Anda dapat menggunakannya kembali di beberapa perintah dengan mereferensikan nama variabel (misalnya, $CLUSTER_NAME) daripada mengetik ulang atau mengganti nilai setiap kali. Pendekatan ini mempermudah proses untuk diikuti dan mengurangi risiko error.

    Untuk menentukan variabel lingkungan 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 GKE_VERSION="1.35.0-gke.1795000"
export AGENT_SANDBOX_VERSION="v0.1.0"
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 variabel lingkungan ini:

    • PROJECT_ID: ID Google Cloud project Anda 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).
    • GKE_LOCATION: Google Cloud region tempat cluster GKE Anda akan dibuat (misalnya, us-central1).
    • GKE_VERSION: versi cluster dan node GKE yang diperlukan agar kompatibel dengan snapshot Pod. Snapshot Pod GKE memerlukan GKE versi 1.34.1-gke.3084001 atau yang lebih baru.
    • AGENT_SANDBOX_VERSION: versi pengontrol Agent Sandbox yang akan di-deploy ke cluster Anda.
    • NODE_POOL_NAME: nama node pool yang akan menjalankan beban kerja 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 cara 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 mengautentikasi.
    • 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 lingkungan Sandbox Agen, Anda perlu melakukan beberapa langkah konfigurasi. Untuk memahami langkah-langkah ini, sebaiknya pahami terlebih dahulu beberapa konsep utama dan kemudian proses snapshot:

    Konsep utama

    • Lingkungan: aplikasi 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 memberikan akses aman ke resource Google Cloud Pod.
    • 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 (eksternal) atau oleh workload sandbox itu sendiri. Dokumen ini menunjukkan pemicu manual yang Anda mulai dengan membuat resource PodSnapshotManualTrigger.
    2. Merekam: GKE merekam status berjalan Pod, 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 Google Cloud resource, lihat Melakukan autentikasi ke API Google Cloud dari workload GKE.

    Untuk mengaktifkan snapshot Pod lingkungan Sandbox Agen, lakukan konfigurasi berikut. Pertama, Anda menyiapkan lingkungan cluster dengan membuat cluster GKE dengan Workload Identity Federation untuk GKE dan fitur snapshot Pod diaktifkan. Selanjutnya, Anda akan mengonfigurasi kebijakan Cloud Storage dan IAM untuk membantu memastikan bahwa 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 berikutnya:

    Topik Tugas
    Penyiapan cluster 1. Buat cluster GKE dan aktifkan fitur snapshot Pod dan Workload Identity Federation untuk GKE.
    2. Deploy Sandbox Agen.
    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. Berikan izin ke pengontrol snapshot.
    Mengonfigurasi resource snapshot 1. Buat PodSnapshotStorageConfig
    2. Buat PodSnapshotPolicy
    3. Membuat SandboxTemplate

    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 Sandbox Agen.

    Membuat cluster GKE

    Buat cluster GKE Standard. Cluster ini menyediakan lingkungan Kubernetes tempat Anda akan mengambil snapshot lingkungan Sandbox Agen. Perintah berikut akan membuat cluster dan mengaktifkan Workload Identity Federation untuk GKE dan fitur snapshot Pod:

    1. Untuk membuat cluster Standar menggunakan Google Cloud CLI, jalankan perintah berikut:

      gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --cluster-version=${GKE_VERSION} \
    --workload-pool=${PROJECT_ID}.svc.id.goog \
    --workload-metadata=GKE_METADATA \
    --num-nodes=1 \
    --enable-pod-snapshots

      Selain membuat cluster, perintah ini mengaktifkan Workload Identity Federation untuk GKE dan fitur snapshot Pod di cluster.

    2. Ambil kredensial cluster agar CLI kubectl dapat terhubung ke cluster. Perintah ini memperbarui file konfigurasi Kubernetes Anda, yang disimpan secara default di direktori ~/.kube/config. File konfigurasi ini berisi kredensial yang diperlukan kubectl untuk berinteraksi dengan cluster GKE Anda:

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

    3. Buat node pool dengan gVisor yang diaktifkan:

      gcloud container node-pools create ${NODE_POOL_NAME} \
    --cluster=${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --machine-type=${MACHINE_TYPE} \
    --node-version=${GKE_VERSION} \
    --image-type=cos_containerd \
    --num-nodes=1 \
    --sandbox type=gvisor

      Perintah ini menggunakan flag utama berikut:

      • --image-type=cos_containerd: menentukan bahwa node menggunakan Container-Optimized OS dengan containerd.
      • --sandbox type=gvisor: mengaktifkan teknologi sandbox gVisor di node, yang diperlukan untuk Agent Sandbox.

    Men-deploy Pengontrol Sandbox Agen 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 Sandbox Agen di cluster Anda.

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

    # Apply the main manifest for the controller and its Custom Resource Definitions (CRDs)
kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml

    Memverifikasi pengontrol

    Setelah menerapkan manifes, periksa apakah Pod pengontrol Sandbox Agen berjalan dengan benar di namespace agent-sandbox-system. Manifes secara otomatis membuat namespace agent-sandbox-system saat Anda menerapkannya di 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 mirip dengan ini:

    NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0      1/1     Running   0          44d

    Setelah pengontrol Agent Sandbox berjalan, pengontrol tersebut dapat membuat dan mengelola lingkungan sandbox secara otomatis 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 kepada sandbox dan pengontrol snapshot untuk mengakses penyimpanan tersebut.

    Buat bucket Cloud Storage

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

    • Aktifkan namespace hierarkis: fitur namespace hierarkis mengatur bucket Anda ke dalam hierarki sistem file, bukan namespace datar. Konfigurasi ini memungkinkan throughput baca dan tulis yang lebih tinggi, dan akibatnya mempercepat penyimpanan dan pemulihan snapshot.
    • Menonaktifkan 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. Sebaiknya 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 memisahkan 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 Anda 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:

      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

    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 yang aman ke resource sandbox Anda: 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 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 Anda ke akun layanan Kubernetes untuk sandbox Anda. Binding ini hanya mengizinkan akun tertentu ini untuk menulis data ke 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="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 Anda.

    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. Kebijakan ini juga menentukan aturan pemicu, seperti apakah snapshot bersifat manual atau dimulai oleh beban kerja sandbox.

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

    kubectl apply -f - <<EOF
apiVersion: podsnapshot.gke.io/v1alpha1
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/v1alpha1
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
EOF

    Memverifikasi konfigurasi

    Setelah Anda menerapkan konfigurasi dan kebijakan penyimpanan snapshot, verifikasi bahwa 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 \
  --namespace "${SNAPSHOT_NAMESPACE}" -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". Respons juga harus menunjukkan bahwa PodSnapshotStorageConfig yang dirujuk 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, Anda membuat resource SandboxTemplate dan SandboxClaim. 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 PodSnapshotPolicy.

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

    Untuk membuat resource SandboxTemplate dan SandboxClaim, terapkan manifes berikut:

    kubectl apply -f - <<EOF
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
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/v1alpha1
kind: SandboxClaim
metadata:
  name: python-sandbox-example
  namespace: ${SNAPSHOT_NAMESPACE}
  labels:
    app: agent-sandbox-workload
spec:
  sandboxTemplateRef:
    name: python-runtime-template
EOF

    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 untuk dibandingkan setelah pemulihan.

      kubectl logs python-sandbox-example --namespace "${SNAPSHOT_NAMESPACE}" --tail=5

      Output 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/v1alpha1
kind: PodSnapshotManualTrigger
metadata:
  name: cpu-snapshot-trigger
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  targetPod: python-sandbox-example
EOF

    3. Verifikasi bahwa 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-example   Complete   XXs

    4. Lihat detail selengkapnya tentang status yang direkam dengan menjelaskan pemicu:

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

      Output 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 memulihkan lingkungan sandbox untuk melanjutkan eksekusi dari status tersimpannya. Untuk memulihkan sandbox, buat SandboxClaim baru yang mereferensikan SandboxTemplate asli. Pengontrol Snapshot Pod otomatis mengidentifikasi dan memulihkan snapshot yang cocok dan terbaru.

    1. Buat SandboxClaim baru untuk memulihkan sandbox:

      kubectl apply -f - <<EOF
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: python-sandbox-from-snapshot
  namespace: ${SNAPSHOT_NAMESPACE}
  labels:
    app: agent-sandbox-workload
spec:
  sandboxTemplateRef:
    name: python-runtime-template
EOF

    2. Verifikasi bahwa pemulihan telah dilakukan dengan melihat log. Perhatikan bahwa penghitung berlanjut dari titik saat snapshot diambil:

      kubectl logs python-sandbox-from-snapshot --namespace "${SNAPSHOT_NAMESPACE}"

      Output akan menampilkan penghitung yang dilanjutkan, misalnya:

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

    Pembersihan

    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 untuk menghentikan Pod yang sedang berjalan dan mengizinkan pengontrol Sandbox Agent untuk menghentikan container secara tuntas.

      kubectl delete sandboxclaims --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 memiliki cakupan cluster, jangan gunakan tanda namespace.

      kubectl delete podsnapshotstorageconfig cpu-pssc-gcs

    5. Hapus namespace Kubernetes untuk menghapus akun layanan Kubernetes secara otomatis dan metadata yang masih ada dalam namespace.

      kubectl delete namespace "${SNAPSHOT_NAMESPACE}"

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

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

    7. Hapus bucket Cloud Storage (opsional) menggunakan perintah penghapusan rekursif jika Anda ingin mereset penyimpanan sepenuhnya. Perhatikan bahwa Anda dapat melewati langkah ini jika Anda 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.}"

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

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

    Langkah berikutnya