Salva e ripristina la sandbox dell'agente negli ambienti GKE con gli snapshot dei pod

Autopilot Standard

Questo documento mostra come utilizzare gli snapshot dei pod GKE per salvare lo stato di un ambiente Agent Sandbox in esecuzione su GKE.

Agent Sandbox su GKE migliora la sicurezza fornendo un ambiente isolato per l'esecuzione di codice non attendibile, come il 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 ti consentono di salvare e ripristinare lo stato degli ambienti in modalità sandbox. Questa funzionalità è utile per i seguenti motivi:

• Avvio rapido: riduci il tempo di avvio della sandbox eseguendo il ripristino da uno snapshot pre-riscaldato.
• Agenti a lunga esecuzione: 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.
• Workload stateful: mantengono il contesto di un agente, ad esempio la cronologia delle conversazioni o i calcoli intermedi, salvando e ripristinando lo stato del suo ambiente in sandbox.
• Riproducibilità: acquisisci uno stato specifico e utilizzalo come base per avviare più nuove 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 workload: l'applicazione in sandbox stessa segnala quando è pronta per essere salvata.

Questo documento mostra come attivare manualmente uno snapshot.

Prima di iniziare

1. 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 cui ti è stato concesso un ruolo.
   • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.
   Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

   Vai al selettore di progetti

2. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

3. Abilita le API Google Kubernetes Engine, Cloud Storage e Identity and Access Management (IAM), se non sono già abilitate.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilita le API

4. Nella console Google Cloud , attiva Cloud Shell.

   Attiva Cloud Shell

Requisiti

Gli snapshot dei pod GKE richiedono GKE 1.35.3-gke.1234000 o versioni successive. Sono supportate entrambe le modalità Autopilot e Standard.

Gli snapshot dei pod richiedono gVisor e non funzionano con le sandbox microVM.

Poiché gli snapshot dei pod richiedono GKE Sandbox, il tuo ambiente è soggetto ad alcune limitazioni. Ad esempio, gli snapshot dei pod non supportano i tipi di macchine E2. Di conseguenza, questo tutorial crea un pool di nodi composto da macchine N2.

Per un elenco completo delle limitazioni, incluse le informazioni sull'utilizzo dei tipi di macchine basate su GPU, consulta Limitazioni e requisiti.

Definisci le variabili di ambiente

Per semplificare i comandi che esegui 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 località 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 nuovamente o sostituire i valori ogni volta. Questo approccio semplifica il processo e riduce il rischio di errori.

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

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

Ecco una spiegazione di queste variabili di ambiente:

• PROJECT_ID: l'ID del progetto Google Cloud corrente. I comandi in questo documento utilizzano questo ID per assegnare un nome alle risorse e concedere le autorizzazioni IAM.
• CLUSTER_NAME: il nome del tuo cluster GKE (ad esempio, agent-sandbox-cluster).
• GKE_LOCATION: la regione Google Cloud per il tuo bucket Cloud Storage (ad esempio, us-central1). Se crei un cluster Autopilot, anche il cluster utilizza questa regione.
• ZONE: la zona del tuo cluster GKE. Se crei un cluster Standard, impostalo su una zona nella regione GKE_LOCATION (ad esempio, us-central1-a). Per ridurre i costi, questo documento crea un cluster Standard di zona.
• AGENT_SANDBOX_VERSION: la versione del controller Agent Sandbox open source da installare. Questo documento utilizza la versione 1.0.6.
• NODE_POOL_NAME: il nome del pool di nodi che eseguirà i workload 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 basate su GPU per i nodi nel tuo pool di nodi, consulta Limitazioni e requisiti. Per informazioni dettagliate sulle diverse serie di macchine e sulla scelta tra le diverse 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 risiederanno il workload e il account di servizio dello snapshot.
• SNAPSHOT_KSA_NAME: il nome del account di servizio Kubernetes che il tuo workload 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 progetto, utilizzato per le associazioni delle autorizzazioni IAM.

Panoramica dei passaggi di configurazione

Per abilitare gli snapshot dei pod di Agent Sandbox negli ambienti GKE, devi eseguire alcuni passaggi di configurazione. Per comprendere questi passaggi, è utile comprendere prima alcuni concetti chiave e poi il processo di creazione degli 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 service account Kubernetes ed è eseguito in uno spazio dei nomi speciale che crei. Insieme, il account di servizio Kubernetes e lo spazio dei nomi formano un'identità univoca che viene 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.

Processo di snapshot

1. Trigger: viene avviato uno snapshot, manualmente (esternamente) o dal workload in sandbox stesso. Questo documento mostra un trigger manuale che avvii creando una risorsa PodSnapshotManualTrigger.
2. Acquisizione: GKE acquisisce lo stato di esecuzione del pod, ad esempio lo stato della memoria del pod e del relativo file system.
3. 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 scoprire di più su come GKE utilizza i service account Kubernetes e i ruoli IAM per accedere alle risorse Google Cloud , consulta Autenticati alle APIGoogle Cloud dai workload GKE.

Per attivare gli snapshot dei pod di Agent Sandbox negli ambienti GKE, 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. In seguito, configurerai i criteri di Cloud Storage e IAM per garantire che gli snapshot vengano archiviati in modo sicuro e che la sandbox disponga delle autorizzazioni necessarie. Infine, crei le risorse snapshot che specificano la località di archiviazione e le policy per la sandbox.

La tabella seguente riepiloga i passaggi di configurazione da eseguire, ognuno dei quali è spiegato nelle sezioni seguenti:

Argomento	Attività
Configurazione del cluster	1. Crea un cluster GKE e abilita le funzionalità di snapshot dei pod e Workload Identity Federation for GKE. 2. Esegui il deployment di Agent Sandbox.
Configura lo spazio di 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 di snapshot.
Configura le risorse degli snapshot	1. Crea unPodSnapshotStorageConfig risorsa 2. Crea una risorsa PodSnapshotPolicy 3. Crea le risorse SandboxTemplate, SandboxWarmPool e SandboxClaim

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 nuovo cluster GKE che soddisfi i requisiti

Crea un nuovo cluster GKE con gli snapshot dei pod abilitati. Gli snapshot dei pod richiedono GKE 1.35.3-gke.1234000 o versioni successive. I comandi seguenti registrano il cluster nel canale di rilascio rapido, la cui versione predefinita soddisfa questo requisito:

Autopilot

Crea un cluster Autopilot con le funzionalità richieste:

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

Standard

Crea un cluster Standard con le funzionalità richieste. Per ridurre i costi, il seguente comando crea un cluster di zona, che esegue il control plane e i nodi in una 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}

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=${ZONE} \
   --project=${PROJECT_ID} \
   --machine-type=${MACHINE_TYPE} \
   --sandbox type=gvisor

Recupera le credenziali

Recupera le credenziali del cluster in modo che l'interfaccia a riga di comando kubectl possa connettersi al cluster:

Autopilot

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

Standard

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

Esegui il deployment del controller Agent Sandbox nel tuo cluster

Puoi eseguire il deployment del controller Agent Sandbox e dei relativi componenti richiesti applicando il manifest della release ufficiale al tuo cluster. Questo manifest è un file di configurazione che indica a Kubernetes di scaricare tutti i componenti necessari per eseguire il deployment e l'esecuzione del controller Agent Sandbox sul tuo cluster.

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

# 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

Per saperne di più sull'installazione di Agent Sandbox, consulta Installa Agent Sandbox su GKE.

Verifica il controller

Dopo aver applicato il manifest, verifica che il pod del controller Agent Sandbox sia in esecuzione correttamente nello spazio dei nomi agent-sandbox-system. Il manifest ha creato automaticamente lo spazio dei nomi agent-sandbox-system quando lo hai applicato nel passaggio precedente.

kubectl get pods -n agent-sandbox-system

Attendi che il pod mostri "Running" nella colonna STATUS e "1/1" nella colonna READY. Quando il pod è in esecuzione correttamente, l'output è simile al seguente:

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

Ora che il controller Agent Sandbox è in esecuzione, può creare e gestire automaticamente ambienti in sandbox per tutte le risorse Sandbox che crei nel tuo cluster.

Configura lo spazio di archiviazione e le autorizzazioni

Questa sezione mostra come configurare lo spazio di archiviazione e le autorizzazioni necessarie per gli snapshot dei pod. Crei un bucket Cloud Storage e una cartella gestita per archiviare i dati degli snapshot. Poi, concedi alla sandbox e al controller di 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 il processo di snapshot sia rapido ed economico, crea il bucket con le seguenti impostazioni:

• Abilita gli 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 un throughput di lettura e scrittura più elevato 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, il processo di snapshot crea ed elimina molti file temporanei durante il caricamento. Disattiva 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 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 per scrivere nel bucket. Puoi concedere questa autorizzazione associando i ruoli IAM Google Cloudal account di servizio Kubernetes utilizzato dai pod. Questa sezione mostra come creare un ruolo IAM personalizzato, creare il account di servizio Kubernetes e configurare le autorizzazioni necessarie.

1. Crea un ruolo IAM personalizzato denominato podSnapshotGcsReadWriter che contenga le autorizzazioni necessarie per scrivere i dati degli snapshot. Se questo ruolo esiste già nel tuo progetto, ad esempio da un'esecuzione precedente di questo documento, salta questo passaggio. In caso contrario, esegui questo comando:

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

   Quando il ruolo viene creato correttamente, l'output è simile al seguente:

   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
   

   Se il comando non riesce e viene visualizzato un errore FAILED_PRECONDITION che indica che l'ID ruolo è stato contrassegnato per l'eliminazione, significa che hai eliminato di recente un ruolo con questo ID, ad esempio nei passaggi di pulizia di un'esecuzione precedente di questo documento. IAM non ti consente di riutilizzare l'ID per un massimo di 37 giorni. Esegui di nuovo il comando con un ID ruolo diverso, ad esempio podSnapshotGcsReadWriter2, e utilizza questo ID anziché podSnapshotGcsReadWriter nel resto di questo documento.

2. Crea lo spazio dei nomi in cui risiederanno la sandbox e il relativo account di servizio:

   kubectl create namespace "${SNAPSHOT_NAMESPACE}"
   

3. Crea il account di servizio Kubernetes nello spazio dei nomi appena creato. Insieme, il account di servizio Kubernetes e lo spazio dei nomi formano un'identità univoca utilizzata per concedere alla sandbox l'accesso sicuro alle risorse Google Cloud:

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

4. 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"
   

5. Concedi il ruolo podSnapshotGcsReadWriter personalizzato al service account Kubernetes per la tua sandbox. Questa associazione consente solo a questo account specifico di scrivere dati nella cartella gestita. Potrebbero essere necessari alcuni minuti prima che un nuovo ruolo personalizzato diventi disponibile, quindi se questo comando non va a buon fine perché il ruolo non esiste, attendi un minuto e poi eseguilo di nuovo:

   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. Concedi il ruolo roles/storage.objectUser al account di servizio Kubernetes. Questo ruolo è necessario affinché l'agente di snapshot dei pod possa 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 di snapshot

Concedi il ruolo objectUser al controller di snapshot del sistema GKE. Questa autorizzazione consente al controller di gestire il ciclo di vita degli 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 workload Agent Sandbox su GKE.

Definisci lo spazio di archiviazione e le regole degli snapshot

Per specificare dove GKE salva gli snapshot e quali regole regolano il processo di creazione degli snapshot, devi creare due risorse personalizzate:

• PodSnapshotStorageConfig: questa risorsa specifica il bucket Cloud Storage e la posizione della cartella in cui GKE salva i file degli snapshot.
• PodSnapshotPolicy: questa risorsa definisce i pod idonei per gli snapshot in base alle relative etichette Kubernetes. Specifica anche le regole di attivazione, ad esempio se gli snapshot sono manuali o avviati dal workload della sandbox. Questo esempio raggruppa gli snapshot in base all'etichetta agents.x-k8s.io/sandbox-name-hash, che il controller Agent Sandbox aggiunge al pod di ogni sandbox. Questo raggruppamento significa che GKE ripristina ogni sandbox solo dai propri snapshot.

Per applicare entrambe le risorse in un unico passaggio, esegui questo comando in Cloud Shell. Questo metodo aiuta 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
  snapshotGroupingRules:
    groupByLabelValue:
      labels:
      - agents.x-k8s.io/sandbox-name-hash
EOF

Verificare la configurazione

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

1. Controlla lo stato della risorsa PodSnapshotStorageConfig:

   kubectl get podsnapshotstorageconfigs.podsnapshot.gke.io cpu-pssc-gcs -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
   

2. 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". Dovrebbe anche indicare che la risorsa PodSnapshotStorageConfig a cui viene fatto riferimento è stata trovata:

   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 template della sandbox

Ora che le policy e le autorizzazioni di archiviazione sono state configurate, crea le risorse SandboxTemplate, SandboxWarmPool e SandboxClaim. La risorsa SandboxWarmPool mantiene in esecuzione una sandbox pre-riscaldata e la risorsa SandboxClaim rivendica la sandbox dal pool. 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 nella risorsa 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 per impostazione predefinita tipi di macchine che non supportano gli snapshot dei pod. Per assicurarti che i tuoi workload vengano eseguiti su hardware compatibile, devi utilizzare una ComputeClass personalizzata per dare la priorità alle famiglie di macchine compatibili.

1. 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: DoNotScaleUp
   

2. Applica il manifest:

   kubectl apply -f non-e2-class.yaml
   

3. Per creare le risorse SandboxTemplate e SandboxWarmPool, applica il seguente manifest. Tieni presente che la risorsa SandboxTemplate fa riferimento alla ComputeClass che hai appena creato utilizzando il selettore di nodi 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
   

Standard

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

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

Dopo aver creato le risorse, rivendica una sandbox dal pool caldo:

1. Attendi che la sandbox del pool caldo sia pronta:

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

2. Crea una risorsa SandboxClaim che rivendica la sandbox dal pool caldo:

   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. Attendi che la richiesta sia pronta, quindi salva il nome della sandbox utilizzata dalla richiesta. Il pod della sandbox ha lo stesso nome della 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}"
   

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

Crea uno snapshot

Questa sezione mostra come attivare manualmente uno snapshot della sandbox in esecuzione. Crei una risorsa trigger che ha come target il pod della sandbox e poi verifichi che il processo di snapshot venga completato correttamente.

1. 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 con cui eseguire il confronto dopo il ripristino.

   kubectl logs "${SANDBOX_NAME}" --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 "Count" stampati.

2. 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: ${SANDBOX_NAME}
   EOF
   

3. 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-warmpool-x7k2p   Complete   XXs
   

4. Visualizza ulteriori 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 di 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 sospendere la sandbox per liberare le sue risorse di computing e riprenderla in un secondo momento dallo stato salvato. Quando sospendi una sandbox, il controller Agent Sandbox elimina il pod della sandbox, ma mantiene la risorsa Sandbox. Quando riprendi la sandbox, il controller ricrea il pod e il controller degli snapshot dei pod ripristina automaticamente il pod dallo snapshot più recente della sandbox.

1. Attendi che lo snapshot sia pronto. GKE ripristina un pod solo da uno snapshot pronto. Se sospendi la sandbox prima che lo snapshot sia pronto, la sandbox si avvia senza lo stato salvato quando la riattivi.

   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. Per sospendere la sandbox, imposta il campo operatingMode su Suspended e poi attendi che il controller elimini il pod della 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. Per riprendere la sandbox, imposta il campo operatingMode su Running, quindi attendi che la sandbox sia pronta:

   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. 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 "${SANDBOX_NAME}" --namespace "${SNAPSHOT_NAMESPACE}"
   

   L'output dovrebbe mostrare la ripresa del contatore, ad esempio:

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

   Se invece il contatore inizia da 0, il pod è stato avviato senza eseguire il ripristino dallo snapshot.

Esegui la pulizia delle risorse

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:

1. Elimina le richieste di sandbox e i pool caldi per arrestare i pod in esecuzione e consentire al controller Agent Sandbox di terminare i container in modo controllato.

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

2. Elimina i template della sandbox e i trigger manuali utilizzati per creare le sandbox e avviare gli snapshot.

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

3. Elimina le policy degli snapshot che definiscono i pod idonei per gli snapshot all'interno del tuo namespace.

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

4. Elimina la configurazione dello spazio di archiviazione degli snapshot, ovvero la definizione globale del backend di archiviazione degli snapshot. Poiché questa risorsa ha un ambito cluster, non utilizzare un flag dello spazio dei nomi.

   kubectl delete podsnapshotstorageconfig cpu-pssc-gcs
   

5. Se ne hai creato uno per Autopilot, elimina ComputeClass.

   kubectl delete computeclass non-e2-class
   

6. Elimina lo spazio dei nomi Kubernetes per rimuovere automaticamente il account di servizio Kubernetes e gli eventuali metadati con spazio dei nomi rimanenti.

   kubectl delete namespace "${SNAPSHOT_NAMESPACE}"
   

7. Elimina il cluster GKE per rimuovere l'infrastruttura sottostante e tutti i nodi associati al tutorial.

   Autopilot

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

   Standard

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

8. 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.}"
   

9. Elimina il ruolo IAM personalizzato (facoltativo) se vuoi riportare il progetto a uno stato completamente pulito. 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 di codice AI con Agent Sandbox su GKE.