Salvare e ripristinare gli ambienti sandbox degli agenti con gli snapshot dei pod

Standard

Questo documento riguarda solo i cluster Standard.

Questo documento mostra come utilizzare gli snapshot dei pod GKE per salvare lo stato di un ambiente sandbox dell'agente in esecuzione.

Agent Sandbox fornisce un ambiente sicuro e isolato per l'esecuzione di codice non attendibile, ad esempio codice generato da modelli linguistici di grandi dimensioni (LLM). L'esecuzione di questo tipo di codice direttamente in un cluster comporta rischi per la sicurezza, perché il codice non attendibile potrebbe potenzialmente accedere o interferire con altre app o con il nodo del cluster sottostante.

Gli snapshot dei pod GKE consentono di salvare e ripristinare lo stato degli ambienti sandbox. Questa funzionalità è utile per i seguenti motivi:

Avvio rapido: riduci i tempi di avvio della sandbox eseguendo il ripristino da uno snapshot pre-riscaldato.
Agenti a esecuzione prolungata: metti in pausa una sandbox che richiede molto tempo per l'esecuzione e riprendila in un secondo momento o spostala in un altro nodo senza perdere i progressi.
Carichi di lavoro stateful: mantengono il contesto di un agente, ad esempio la cronologia delle conversazioni o i calcoli intermedi, salvando e ripristinando lo stato del relativo ambiente sandbox.
Riproducibilità: acquisisci uno stato specifico e utilizzalo come base per avviare più sandbox con lo stesso stato inizializzato.

Uno snapshot può essere attivato in due modi:

Trigger manuale:crei una risorsa PodSnapshotManualTrigger per attivare lo snapshot.
Trigger del carico di lavoro:l'applicazione in sandbox segnala quando è pronta per essere salvata.

Questo documento mostra come attivare manualmente uno snapshot.

Nota:gli snapshot dei pod GKE sono una funzionalità di anteprima.

Prima di iniziare

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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
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

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

Requisiti

Per utilizzare gli snapshot dei pod GKE, devi disporre di un cluster in modalità Standard che esegue GKE versione 1.34.1-gke.3084001 o successive. Ti consigliamo di utilizzare GKE 1.35 o versioni successive. La versione 1.34 di GKE presenta un problema noto per cui il checkpoint potrebbe non riuscire con un errore di input/output relativo ai bug delle autorizzazioni di Cloud Storage.

Gli snapshot dei pod non supportano i tipi di macchine E2. Di conseguenza, questo tutorial crea un pool di nodi costituito da macchine N2.

Se vuoi utilizzare tipi di macchine basati su GPU per i nodi nel pool di nodi, consulta la sezione Limitazioni e requisiti.

Definisci le variabili di ambiente

Per semplificare i comandi eseguiti in questo documento, puoi impostare le variabili di ambiente in Cloud Shell. Queste variabili memorizzano valori come l'ID del tuo progetto Google Cloud , il nome del bucket Cloud Storage che memorizzerà gli snapshot e la posizione del tuo cluster GKE.

Dopo aver definito queste variabili, puoi riutilizzarle in più comandi facendo riferimento al nome della variabile (ad esempio, $CLUSTER_NAME) anziché digitare o sostituire i valori ogni volta. Questo approccio semplifica la procedura e riduce il rischio di errori.

Per definire le seguenti variabili di ambiente utili in Cloud Shell, esegui i seguenti comandi:

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

Ecco una spiegazione di queste variabili di ambiente:

PROJECT_ID: l'ID del tuo progetto Google Cloud corrente. La definizione di questa variabile consente di garantire che tutte le risorse, come il cluster GKE, vengano create nel progetto corretto.
CLUSTER_NAME: il nome del tuo cluster GKE (ad esempio, agent-sandbox-cluster).
GKE_LOCATION: la Google Cloud regione in cui verrà creato il cluster GKE (ad esempio, us-central1).
GKE_VERSION: la versione del cluster GKE e del nodo richiesta per la compatibilità con gli snapshot dei pod. Gli snapshot dei pod GKE richiedono GKE 1.34.1-gke.3084001 o versioni successive.
AGENT_SANDBOX_VERSION: la versione del controller Agent Sandbox da implementare nel cluster.
NODE_POOL_NAME: il nome del pool di nodi che eseguirà i carichi di lavoro in sandbox (ad esempio, agent-sandbox-node-pool).
MACHINE_TYPE: il tipo di macchina dei nodi nel pool di nodi (ad esempio, n2-standard-2). Gli snapshot dei pod non supportano i tipi di macchina E2. Se vuoi utilizzare tipi di macchine basati su GPU per i nodi nel pool di nodi, consulta Limitazioni e requisiti. Per informazioni dettagliate sulle diverse serie di macchine e sulla scelta tra le varie opzioni, consulta la guida alle risorse e al confronto per le famiglie di macchine.
SNAPSHOTS_BUCKET_NAME: il nome del bucket Cloud Storage che creerai per archiviare gli snapshot.
SNAPSHOT_NAMESPACE: lo spazio dei nomi Kubernetes in cui si troveranno il workload e il account di servizio dello snapshot.
SNAPSHOT_KSA_NAME: il nome del account di servizio Kubernetes che il tuo carico di lavoro utilizzerà per l'autenticazione.
SNAPSHOT_FOLDER: la directory all'interno del bucket Cloud Storage in cui verranno organizzati gli snapshot.
PROJECT_NUMBER: l'identificatore numerico univoco del tuo progetto, utilizzato per i binding delle autorizzazioni IAM.

Panoramica dei passaggi di configurazione

Per abilitare gli snapshot dei pod degli ambienti sandbox dell'agente, devi eseguire alcuni passaggi di configurazione. Per comprendere questi passaggi, è utile innanzitutto capire alcuni concetti chiave e poi la procedura di snapshot:

Concetti fondamentali

Ambiente:un'applicazione in sandbox viene eseguita all'interno di un pod Kubernetes su un nodo del cluster GKE.
Identità:il pod è associato a un account di servizio Kubernetes e viene eseguito in uno spazio dei nomi speciale che crei. Insieme, il account di servizio Kubernetes e lo spazio dei nomi formano un'identità univoca utilizzata per concedere al pod l'accesso sicuro alle risorse Google Cloud .
Autorizzazioni: per consentire il salvataggio degli snapshot in Cloud Storage, all'identità del pod devono essere concesse autorizzazioni IAM specifiche che consentano di scrivere in un bucket Cloud Storage.

Procedura di snapshot

Trigger:viene avviato uno snapshot, manualmente (esternamente) o dal carico di lavoro in sandbox stesso. Questo documento mostra un trigger manuale che avvii creando una risorsa PodSnapshotManualTrigger.
Acquisizione:GKE acquisisce lo stato di esecuzione del pod, ad esempio lo stato della memoria del pod e del relativo file system.
Caricamento:utilizzando le autorizzazioni concesse al service account Kubernetes del pod, GKE carica lo stato acquisito come file snapshot nel bucket Cloud Storage designato.

Per saperne di più su come GKE utilizza gli account di servizio Kubernetes e i ruoli IAM per accedere alle risorse Google Cloud , consulta Autenticarsi alle API Google Cloud dai carichi di lavoro GKE.

Per abilitare gli snapshot dei pod degli ambienti sandbox dell'agente, esegui la seguente configurazione. Innanzitutto, prepara un ambiente cluster creando un cluster GKE con la federazione delle identità per i carichi di lavoro per GKE e le funzionalità di snapshot dei pod abilitate. Successivamente, configura le policy Cloud Storage e IAM per assicurarti che gli snapshot vengano archiviati in modo sicuro e che la sandbox disponga delle autorizzazioni necessarie. Infine, crei le risorse snapshot che specificano la posizione di archiviazione e le policy per la sandbox.

La tabella seguente riepiloga i passaggi di configurazione che devi eseguire e ogni passaggio è spiegato nelle sezioni successive:

Argomento	Attività
Configurazione del cluster	1. Crea un cluster GKE e abilita le funzionalità degli snapshot dei pod e di Workload Identity Federation for GKE. 2. Esegui il deployment della sandbox dell'agente.
Configurare l'archiviazione e le autorizzazioni	1. Crea il bucket Cloud Storage e la cartella gestita. 2. Crea il ruolo IAM personalizzato. 3. Crea lo spazio dei nomi Kubernetes e il account di servizio Kubernetes (KSA). 4. Associa il ruolo IAM al service account Kubernetes. 5. Concedi le autorizzazioni al controller snapshot.
Configurare le risorse snapshot	1. Crea `PodSnapshotStorageConfig` 2. Crea `PodSnapshotPolicy` 3. Crea `SandboxTemplate`

Configurazione del cluster

Un'app in sandbox viene eseguita all'interno di un pod su un nodo del cluster GKE, quindi devi configurare un ambiente cluster. Questa sezione mostra come creare un cluster GKE ed eseguire il deployment del controller Agent Sandbox.

Crea un cluster GKE

Crea un cluster GKE Standard. Questo cluster fornisce l'ambiente Kubernetes in cui acquisirai uno snapshot di un ambiente sandbox dell'agente. Il seguente comando crea il cluster e abilita la federazione delle identità per i carichi di lavoro per GKE e la funzionalità degli snapshot dei pod:

Per creare un cluster Standard utilizzando Google Cloud CLI, esegui il comando seguente:

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

Oltre a creare il cluster, questo comando abilita la federazione delle identità per i carichi di lavoro per GKE e la funzionalità degli snapshot dei pod sul cluster.

Recupera le credenziali del cluster in modo che la CLI kubectl possa connettersi al cluster. Questo comando aggiorna il file di configurazione di Kubernetes, che per impostazione predefinita è archiviato nella directory ~/.kube/config. Questo file di configurazione contiene le credenziali richieste da kubectl per interagire con il tuo cluster GKE:
```
gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}
```

Crea un pool di nodi con gVisor abilitato:

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

Questo comando utilizza i seguenti flag chiave:

--image-type=cos_containerd: specifica che i nodi utilizzano Container-Optimized OS con containerd.
--sandbox type=gvisor: abilita la tecnologia sandbox gVisor sui nodi, necessaria per la sandbox dell'agente.

Esegui il deployment del controller sandbox dell'agente nel cluster

Puoi eseguire il deployment del controller Agent Sandbox e dei relativi componenti richiesti applicando i manifest di rilascio ufficiali al cluster. Questi manifest sono file di configurazione che indicano a Kubernetes di scaricare tutti i componenti necessari per eseguire il deployment e l'esecuzione del controller Agent Sandbox sul cluster.

Per eseguire il deployment di Agent Sandbox nel cluster GKE, esegui questo comando:

# 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

Verificare il controller

Dopo aver applicato i manifest, verifica che il pod del controller Agent Sandbox venga eseguito correttamente nello spazio dei nomi agent-sandbox-system. I manifest hanno creato automaticamente lo spazio dei nomi agent-sandbox-system quando li hai applicati nel passaggio precedente.

kubectl get pods -n agent-sandbox-system

Attendi che il pod mostri "Running" (In esecuzione) nella colonna STATUS e "1/1" nella colonna READY. Quando il pod è in esecuzione correttamente, l'output è simile a questo:

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

Ora che il controller Agent Sandbox è in esecuzione, può creare e gestire automaticamente ambienti sandbox per qualsiasi risorsa Sandbox creata nel cluster.

Configurare l'archiviazione e le autorizzazioni

Questa sezione mostra come configurare lo spazio di archiviazione e le autorizzazioni richieste per gli snapshot dei pod. Crea un bucket Cloud Storage e una cartella gestita per archiviare i dati dello snapshot. Dopodiché, concedi alla sandbox e al controller dello snapshot le autorizzazioni necessarie per accedere allo spazio di archiviazione.

Crea il bucket Cloud Storage

Crea un bucket per archiviare gli snapshot. Per garantire che la procedura di snapshot sia rapida ed economica, ti consigliamo di creare il bucket con le seguenti impostazioni:

Abilita spazi dei nomi gerarchici:la funzionalità degli spazi dei nomi gerarchici organizza il bucket in una gerarchia di file system anziché in uno spazio dei nomi piatto. Questa configurazione consente una velocità effettiva di lettura e scrittura più elevata e, di conseguenza, velocizza il salvataggio e il ripristino degli snapshot.
Disattiva l'eliminazione temporanea:la funzionalità di eliminazione temporanea protegge i dati conservando i file eliminati per un periodo di tempo prestabilito. Tuttavia, la procedura di snapshot crea ed elimina molti file temporanei durante il caricamento. Ti consigliamo di disattivare l'eliminazione temporanea per evitare addebiti non necessari per l'archiviazione di questi file temporanei.

Per creare il bucket con queste impostazioni, esegui questo comando:

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

Crea una cartella gestita

Crea una cartella gestita per organizzare gli snapshot all'interno del bucket. Le cartelle gestite ti consentono di applicare le autorizzazioni IAM a una cartella specifica anziché all'intero bucket. Questo accesso a livello di cartella limita l'accesso della sandbox solo ai propri snapshot e li isola dagli altri dati nel bucket.

Per creare una cartella gestita, esegui questo comando:

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

Configura il account di servizio e i ruoli IAM

Per consentire a GKE di salvare gli snapshot in modo sicuro, il service account Kubernetes utilizzato dai pod che eseguono il workload in sandbox deve disporre dell'autorizzazione di scrittura nel bucket. Concedi questa autorizzazione associando i ruoli IAM all'account di servizio Kubernetes utilizzato dai pod. Google Cloud Questa sezione mostra come creare un ruolo IAM personalizzato, creare il account di servizio Kubernetes e configurare le autorizzazioni necessarie.

Crea un ruolo IAM personalizzato denominato podSnapshotGcsReadWriter che contenga le autorizzazioni necessarie per scrivere i dati dello snapshot:

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

Una volta creato correttamente il ruolo, l'output ha il seguente aspetto:

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

Crea lo spazio dei nomi in cui risiederanno la sandbox e il relativo account di servizio:
```
kubectl create namespace "${SNAPSHOT_NAMESPACE}"
```
Crea il account di servizio Kubernetes nello spazio dei nomi che hai appena creato. Insieme, il account di servizio Kubernetes e lo spazio dei nomi formano un'identità unica utilizzata per concedere all'ambiente sandbox l'accesso sicuro alle risorse: Google Cloud
```
kubectl create serviceaccount "${SNAPSHOT_KSA_NAME}" \
    --namespace "${SNAPSHOT_NAMESPACE}"
```

Concedi il ruolo roles/storage.bucketViewer a tutti i service account nello spazio dei nomi. Questo ruolo consente agli account di visualizzare i metadati del bucket, ma non di leggere o scrivere i dati stessi:

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"

Concedi il ruolo podSnapshotGcsReadWriter personalizzato al service account Kubernetes per la sandbox. Questo binding consente solo a questo account specifico di scrivere dati nella cartella gestita:

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"

Concedi il ruolo roles/storage.objectUser all'account di servizio Kubernetes. Questo ruolo è necessario per l'agente di snapshot del pod per eseguire operazioni sulle cartelle gestite:

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"

Concedi le autorizzazioni al controller snapshot

Assegna il ruolo objectUser al controller snapshot del sistema GKE. Questa autorizzazione consente al controller di gestire il ciclo di vita dello snapshot, ad esempio eliminare gli oggetti snapshot quando elimini una risorsa 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"

Configura le risorse degli snapshot

Questa sezione mostra come configurare le risorse snapshot per il carico di lavoro sandbox dell'agente.

Definisci l'archiviazione e le regole degli snapshot

Per specificare dove GKE salva gli snapshot e quali regole regolano il processo di snapshot, crea due risorse personalizzate:

PodSnapshotStorageConfig: questa risorsa specifica il bucket Cloud Storage e la posizione della cartella in cui GKE salva i file snapshot.
PodSnapshotPolicy: questa risorsa definisce quali pod sono idonei per gli snapshot in base alle loro etichette Kubernetes. Specifica inoltre le regole di attivazione, ad esempio se gli snapshot sono manuali o avviati dal carico di lavoro sandbox.

Per applicare entrambe le risorse in un unico passaggio, esegui questo comando in Cloud Shell. Questo metodo contribuisce a garantire che le variabili di ambiente vengano inserite correttamente:

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

Verificare la configurazione

Dopo aver applicato la configurazione e il criterio di archiviazione degli snapshot, verifica che le risorse siano pronte all'uso. Questa sezione mostra come controllare lo stato di queste risorse personalizzate.

Controlla lo stato della risorsa PodSnapshotStorageConfig:

kubectl get podsnapshotstorageconfigs.podsnapshot.gke.io cpu-pssc-gcs \
  --namespace "${SNAPSHOT_NAMESPACE}" -o yaml

L'output dovrebbe contenere una condizione con type: Ready e status: "True":

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

Controlla lo stato della risorsa PodSnapshotPolicy:

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

L'output dovrebbe contenere una condizione con type: Ready e status: "True". Deve anche indicare che è stato trovato il PodSnapshotStorageConfig a cui viene fatto riferimento:

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

Crea il modello di sandbox

Ora che sono state implementate le norme e le autorizzazioni di archiviazione, crea le risorse SandboxTemplate e SandboxClaim. Affinché il processo di snapshot funzioni, il sandbox deve essere eseguito con il account di servizio Kubernetes creato in precedenza in questo documento. La sandbox deve avere anche le etichette che hai specificato in precedenza in PodSnapshotPolicy.

Questo esempio utilizza un'app Python che stampa un contatore incrementale nei log. Questo contatore ti consente di verificare che lo stato venga salvato correttamente e ripristinato in un secondo momento.

Per creare le risorse SandboxTemplate e SandboxClaim, applica il seguente manifest:

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

La sandbox è ora in esecuzione con l'identità corretta ed è pronta per essere acquisita.

Crea uno snapshot

Questa sezione mostra come attivare manualmente uno snapshot della sandbox in esecuzione. Crea una risorsa trigger che ha come target il pod sandbox e poi verifica che la procedura di snapshot venga completata correttamente.

Controlla i log del contatore iniziale:prima di attivare lo snapshot, visualizza i log della sandbox in esecuzione per vedere il valore attuale del contatore. La visualizzazione dei log stabilisce una base di riferimento da confrontare dopo il ripristino.
```
kubectl logs python-sandbox-example --namespace "${SNAPSHOT_NAMESPACE}" --tail=5
```
L'output mostra le ultime righe del contatore, ad esempio:
```
Count: 15
Count: 16
Count: 17
```
Prendi nota degli ultimi valori di "Conteggio" stampati.

Crea una risorsa PodSnapshotManualTrigger: avvia lo 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

Verifica che l'attivazione manuale sia andata a buon fine:

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

L'output dovrebbe mostrare lo stato Complete, che indica che GKE ha attivato correttamente lo snapshot del pod di destinazione:

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

Visualizza maggiori dettagli sullo stato acquisito descrivendo il trigger:

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

L'output contiene una sezione Snapshot Created con il nome univoco dei file dello snapshot archiviati nel bucket:

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>

Esegui il ripristino da uno snapshot

Dopo aver acquisito uno snapshot, puoi ripristinare l'ambiente sandbox per riprendere l'esecuzione dallo stato salvato. Per ripristinare la sandbox, crea un nuovo SandboxClaim che faccia riferimento al SandboxTemplate originale. Il controller Pod Snapshot identifica e ripristina automaticamente lo snapshot corrispondente più recente.

Crea un nuovo SandboxClaim per ripristinare la 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

Verifica che il ripristino sia avvenuto visualizzando i log. Tieni presente che il contatore continua dal punto in cui è stato acquisito lo snapshot:
```
kubectl logs python-sandbox-from-snapshot --namespace "${SNAPSHOT_NAMESPACE}"
```
L'output dovrebbe mostrare la ripresa del conteggio, ad esempio:
```
Count: 18
Count: 19
Count: 20
Count: 21
```

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo documento, segui questi passaggi per eliminare le risorse che hai creato:

Elimina le rivendicazioni della sandbox per arrestare tutti i pod in esecuzione e consentire al controller della sandbox dell'agente di terminare i container in modo controllato.
```
kubectl delete sandboxclaims --all --namespace "${SNAPSHOT_NAMESPACE}"
```

Elimina i modelli sandbox e i trigger manuali utilizzati per creare sandbox e avviare snapshot.

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

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

Elimina i criteri di snapshot che definiscono quali pod sono idonei per gli snapshot all'interno del tuo spazio dei nomi.
```
kubectl delete podsnapshotpolicy cpu-psp --namespace "${SNAPSHOT_NAMESPACE}"
```
Elimina la configurazione dell'archiviazione degli snapshot, ovvero la definizione globale del backend di archiviazione degli snapshot. Poiché questa risorsa ha ambito cluster, non utilizzare un flag dello spazio dei nomi.
```
kubectl delete podsnapshotstorageconfig cpu-pssc-gcs
```
Elimina lo spazio dei nomi Kubernetes per rimuovere automaticamente il account di servizio Kubernetes e tutti i metadati con spazio dei nomi rimanenti.
```
kubectl delete namespace "${SNAPSHOT_NAMESPACE}"
```
Elimina il cluster GKE per rimuovere l'infrastruttura sottostante e tutti i nodi associati al tutorial.
```
gcloud container clusters delete "${CLUSTER_NAME}" --location="${GKE_LOCATION}" --quiet
```
Elimina il bucket Cloud Storage (facoltativo) utilizzando il comando di rimozione ricorsiva se vuoi reimpostare completamente lo spazio di archiviazione. Tieni presente che puoi saltare questo passaggio se intendi riutilizzare il bucket configurato correttamente per i test futuri.
```
gcloud storage rm --recursive "gs://${SNAPSHOTS_BUCKET_NAME:?Error: SNAPSHOTS_BUCKET_NAME is not set. Please re-define the environment variables you defined earlier.}"
```
Elimina il ruolo IAM personalizzato (facoltativo) se vuoi ripristinare lo stato completamente pulito del progetto. Poiché i ruoli IAM persistono anche dopo l'eliminazione del cluster, devi eliminarli separatamente.
```
gcloud iam roles delete podSnapshotGcsReadWriter --project="${PROJECT_ID}"
```

Passaggi successivi

Scopri di più sugli snapshot dei pod GKE.
Scopri di più sul progetto open source Agent Sandbox su GitHub.
Scopri come isolare l'esecuzione del codice AI con Agent Sandbox.