Questo documento mostra come utilizzare gli snapshot dei pod GKE per salvare lo stato di un ambiente Agent Sandbox in esecuzione.
Agent Sandbox migliora la sicurezza fornendo un ambiente 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 stesso.
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
PodSnapshotManualTriggerper 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.
Prima di iniziare
-
Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .
Ruoli richiesti per selezionare o creare un progetto
- Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
-
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto
(
roles/resourcemanager.projectCreator), che contiene l'autorizzazioneresourcemanager.projects.create. Scopri come concedere i ruoli.
-
Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .
Attiva le API Google Kubernetes Engine, Cloud Storage e Identity and Access Management (IAM).
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (
roles/serviceusage.serviceUsageAdmin), che include l'autorizzazioneserviceusage.services.enable. Scopri come concedere i ruoli.-
Nella console Google Cloud , attiva Cloud Shell.
Requisiti
Gli snapshot dei pod GKE richiedono GKE versione 1.35.3-gke.1234000 o successive. Sono supportate sia la modalità Autopilot che quella Standard.
Poiché gli snapshot dei pod richiedono GKE Sandbox, il tuo ambiente è soggetto a determinate limitazioni. Ad esempio, gli snapshot dei pod non supportano i tipi di macchine E2. Di conseguenza, questo tutorial crea un pool di nodi costituito da macchine N2.
Per un elenco completo delle limitazioni, incluse le informazioni sull'utilizzo dei tipi di macchine basati su GPU, consulta 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à i tuoi 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 CLUSTER_VERSION="1.35.3-gke.1234000"
export AGENT_SANDBOX_VERSION="v0.4.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)")
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).CLUSTER_VERSION: la versione del cluster GKE che deve essere la versione 1.35.3-gke.1234000 o 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 Workload Identity Federation for 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:
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 e come eseguire il deployment del controller Agent Sandbox.
Crea un nuovo cluster GKE che soddisfi i requisiti
Crea un nuovo cluster GKE con gli snapshot dei pod abilitati. Per la piena compatibilità delle funzionalità, specifica un cluster versione 1.35.3-gke.1234000 o successiva:
Autopilot
Crea un cluster Autopilot con le funzionalità richieste:
gcloud container clusters create-auto ${CLUSTER_NAME} \
--cluster-version=${CLUSTER_VERSION} \
--enable-pod-snapshots \
--location=${GKE_LOCATION}
Standard
Crea un cluster standard con le funzionalità richieste:
gcloud container clusters create ${CLUSTER_NAME} \
--cluster-version=${CLUSTER_VERSION} \
--enable-pod-snapshots \
--machine-type=${MACHINE_TYPE} \
--workload-pool=${PROJECT_ID}.svc.id.goog \
--workload-metadata=GKE_METADATA \
--num-nodes=1 \
--location=${GKE_LOCATION}
Crea un pool di nodi con GKE Sandbox abilitato. GKE Sandbox è una funzionalità di sicurezza dei container basata sul progetto open source gVisor che fornisce un ulteriore livello di isolamento tra le applicazioni in esecuzione e il sistema operativo host:
gcloud container node-pools create ${NODE_POOL_NAME} \
--cluster ${CLUSTER_NAME} \
--num-nodes=1 \
--location=${GKE_LOCATION} \
--project=${PROJECT_ID} \
--machine-type=${MACHINE_TYPE} \
--sandbox type=gvisor
Recuperare le credenziali
Recupera le credenziali del cluster in modo che la CLI kubectl possa connettersi
al cluster:
gcloud container clusters get-credentials ${CLUSTER_NAME} \
--location=${GKE_LOCATION}
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 in 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
podSnapshotGcsReadWriterche 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: podSnapshotGcsReadWriterCrea 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.bucketViewera 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
podSnapshotGcsReadWriterpersonalizzato 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.objectUserall'account di servizio Kubernetes. Questo ruolo è necessario per l'agente 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 eliminando 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 di Agent Sandbox.
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/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
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 yamlL'output dovrebbe contenere una condizione con
type: Readyestatus: "True":status: conditions: - lastTransitionTime: "2025-10-31T18:18:02Z" message: Valid PodSnapshotStorageConfig reason: StorageConfigValid status: "True" type: ReadyControlla lo stato della risorsa
PodSnapshotPolicy:kubectl get podsnapshotpolicies.podsnapshot.gke.io cpu-psp \ --namespace "${SNAPSHOT_NAMESPACE}" -o yamlL'output dovrebbe contenere una condizione con
type: Readyestatus: "True". Deve anche indicare che è stato trovato ilPodSnapshotStorageConfiga 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 di archiviazione e le autorizzazioni, crea le risorse
SandboxTemplate e SandboxClaim. Affinché il processo di snapshot funzioni, la sandbox deve essere eseguita con il account di servizio Kubernetes che hai 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.
Autopilot
Gli snapshot dei pod non supportano i tipi di macchine E2. In Autopilot, GKE potrebbe utilizzare i nodi E2 per impostazione predefinita. Per contribuire a garantire che i tuoi workload vengano eseguiti su hardware compatibile, devi utilizzare una ComputeClass personalizzata per dare la priorità alle famiglie di macchine compatibili.
Salva il seguente manifest come
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: DoNotScaleUpApplica il manifest:
kubectl apply -f non-e2-class.yamlPer creare le risorse
SandboxTemplateeSandboxClaim, applica il seguente manifest. Tieni presente cheSandboxTemplatesi riferisce aComputeClassche hai appena creato utilizzando il selettore di nodicloud.google.com/compute-class: non-e2-class.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 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/v1alpha1 kind: SandboxClaim metadata: name: python-sandbox-example namespace: ${SNAPSHOT_NAMESPACE} labels: app: agent-sandbox-workload spec: sandboxTemplateRef: name: python-runtime-template EOF
Standard
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=5L'output mostra le ultime righe del contatore, ad esempio:
Count: 15 Count: 16 Count: 17Prendi nota degli ultimi valori di "Conteggio" stampati.
Crea una risorsa PodSnapshotManualTrigger: avvia lo snapshot:
kubectl apply -f - <<EOF apiVersion: podsnapshot.gke.io/v1 kind: PodSnapshotManualTrigger metadata: name: cpu-snapshot-trigger namespace: ${SNAPSHOT_NAMESPACE} spec: targetPod: python-sandbox-example EOFVerifica 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 XXsVisualizza 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 Createdcon 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
SandboxClaimper 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 EOFVerifica 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 contatore, ad esempio:
Count: 18 Count: 19 Count: 20 Count: 21
Libera spazio
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-gcsSe ne hai creato uno per Autopilot, elimina ComputeClass.
kubectl delete computeclass non-e2-classElimina 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}" --quietElimina 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.