Cómo guardar y restablecer entornos de Agent Sandbox con instantáneas de Pod

Estándar

Este documento solo se aplica a los clústeres estándar.

En este documento, se muestra cómo usar las instantáneas de Pod de GKE para guardar el estado de un entorno de Agent Sandbox en ejecución.

Agent Sandbox proporciona un entorno seguro y aislado para ejecutar código no confiable, como el código generado por modelos de lenguaje grandes (LLM). Ejecutar este tipo de código directamente en un clúster plantea riesgos de seguridad, ya que el código no confiable podría acceder a otras apps o al nodo del clúster subyacente, o bien interferir en ellos.

Las instantáneas de Pods de GKE te permiten guardar y restablecer el estado de los entornos de zona de pruebas. Esta funcionalidad es útil por los siguientes motivos:

Inicio rápido: Reduce el tiempo de inicio de la zona de pruebas restableciendo una instantánea precalentada.
Agentes de larga duración: Pausa una zona de pruebas que tarda mucho en ejecutarse y reanúdala más tarde, o muévela a un nodo diferente sin perder el progreso.
Cargas de trabajo con estado: Persisten el contexto de un agente, como el historial de conversaciones o los cálculos intermedios, guardando y restableciendo el estado de su entorno de zona de pruebas.
Reproducibilidad: Captura un estado específico y úsalo como base para iniciar varios entornos de pruebas nuevos con el mismo estado inicializado.

Se puede activar una instantánea de dos maneras:

Activador manual: Creas un recurso PodSnapshotManualTrigger para activar la instantánea.
Activador de carga de trabajo: La propia aplicación en zona de pruebas indica cuándo está lista para guardarse.

En este documento, se muestra cómo activar manualmente una instantánea.

Nota: Las instantáneas de Pods de GKE son una función en versión preliminar.

Antes de comenzar

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

Requisitos

Para usar las instantáneas de Pod de GKE, necesitas un clúster en modo estándar que ejecute la versión 1.34.1-gke.3084001 de GKE o una posterior. Te recomendamos que uses la versión 1.35 o posterior de GKE. La versión 1.34 de GKE tiene un problema conocido en el que es posible que la creación de puntos de control falle con un error de entrada/salida relacionado con errores de permisos de Cloud Storage.

Las instantáneas de Pod no admiten tipos de máquinas E2. Por lo tanto, en este instructivo, se crea un grupo de nodos que consta de máquinas N2.

Si deseas usar tipos de máquinas basados en GPU para los nodos de tu grupo de nodos, consulta Limitaciones y requisitos.

Define las variables de entorno

Para simplificar los comandos que ejecutas en este documento, puedes configurar variables de entorno en Cloud Shell. Estas variables almacenan valores como el ID de tu proyecto de Google Cloud , el nombre del bucket de Cloud Storage que almacenará tus instantáneas y la ubicación de tu clúster de GKE.

Después de definir estas variables, puedes volver a usarlas en varios comandos haciendo referencia al nombre de la variable (por ejemplo, $CLUSTER_NAME) en lugar de volver a escribir o reemplazar los valores cada vez. Este enfoque facilita el proceso y reduce el riesgo de errores.

Para definir las siguientes variables de entorno útiles en Cloud Shell, ejecuta los siguientes comandos:

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

A continuación, se explica cada una de estas variables de entorno:

PROJECT_ID: Es el ID de tu proyecto actual de Google Cloud . Definir esta variable ayuda a garantizar que todos los recursos, como tu clúster de GKE, se creen en el proyecto correcto.
CLUSTER_NAME: Es el nombre del clúster de GKE (por ejemplo, agent-sandbox-cluster).
GKE_LOCATION: La región Google Cloud en la que se creará tu clúster de GKE (por ejemplo, us-central1).
GKE_VERSION: Es la versión del clúster y del nodo de GKE que se requiere para la compatibilidad con las instantáneas de Pods. Las instantáneas de Pods de GKE requieren la versión 1.34.1-gke.3084001 o posterior de GKE.
AGENT_SANDBOX_VERSION: Es la versión del controlador de Agent Sandbox que se implementará en tu clúster.
NODE_POOL_NAME: Es el nombre del grupo de nodos que ejecutará cargas de trabajo en zona de pruebas (por ejemplo, agent-sandbox-node-pool).
MACHINE_TYPE: Es el tipo de máquina de los nodos en tu grupo de nodos (por ejemplo, n2-standard-2). Las instantáneas de Pod no admiten tipos de máquinas E2. Si deseas usar tipos de máquinas basados en GPU para los nodos de tu grupo de nodos, consulta Limitaciones y requisitos. Para obtener detalles sobre las diferentes series de máquinas y elegir entre las distintas opciones, consulta la guía de comparación y recursos de familias de máquinas.
SNAPSHOTS_BUCKET_NAME: Es el nombre del bucket de Cloud Storage que crearás para almacenar instantáneas.
SNAPSHOT_NAMESPACE: Es el espacio de nombres de Kubernetes en el que residirán tu carga de trabajo de instantáneas y tu cuenta de servicio.
SNAPSHOT_KSA_NAME: Es el nombre de la cuenta de servicio de Kubernetes que usará tu carga de trabajo para la autenticación.
SNAPSHOT_FOLDER: Es el directorio dentro de tu bucket de Cloud Storage en el que se organizarán las instantáneas.
PROJECT_NUMBER: Es el identificador numérico único de tu proyecto, que se usa para las vinculaciones de permisos de IAM.

Descripción general de los pasos de configuración

Para habilitar las instantáneas de Pod de los entornos de Agent Sandbox, debes realizar algunos pasos de configuración. Para comprender estos pasos, primero es útil conocer algunos conceptos clave y, luego, el proceso de instantáneas:

Conceptos clave

Entorno: Una aplicación en zona de pruebas se ejecuta dentro de un Pod de Kubernetes en un nodo del clúster de GKE.
Identidad: El Pod está asociado con una cuenta de servicio de Kubernetes y se ejecuta en un espacio de nombres especial que creas. En conjunto, la cuenta de servicio de Kubernetes y el espacio de nombres forman una identidad única que se usa para otorgar al Pod acceso seguro a los recursos de Google Cloud .
Permisos: Para permitir que se guarden instantáneas en Cloud Storage, se debe otorgar a la identidad del Pod permisos específicos de IAM que le permitan escribir en un bucket de Cloud Storage.

Proceso de instantáneas

Activador: Se inicia una instantánea, ya sea de forma manual (externa) o por la propia carga de trabajo en zona de pruebas. En este documento, se muestra un activador manual que se inicia creando un recurso PodSnapshotManualTrigger.
Captura: GKE captura el estado de ejecución del Pod, como el estado de la memoria del Pod y su sistema de archivos.
Carga: Con los permisos otorgados a la cuenta de servicio de Kubernetes del Pod, GKE sube el estado capturado como archivos de instantáneas al bucket de Cloud Storage designado.

Para obtener más información sobre cómo GKE usa las cuentas de servicio de Kubernetes y los roles de IAM para acceder a los recursos de Google Cloud , consulta Valida en las APIs de Google Cloud desde cargas de trabajo de GKE.

Para habilitar las instantáneas de Pod de los entornos de Agent Sandbox, realiza la siguiente configuración. Primero, prepara un entorno de clúster creando un clúster de GKE con la federación de identidades para cargas de trabajo para GKE y las funciones de instantáneas de Pod habilitadas. A continuación, configurarás Cloud Storage y las políticas de IAM para garantizar que tus instantáneas se almacenen de forma segura y que tu zona de pruebas tenga los permisos necesarios. Por último, creas los recursos de instantáneas que especifican la ubicación de almacenamiento y las políticas de tu zona de pruebas.

En la siguiente tabla, se resumen los pasos de configuración que debes realizar, y cada paso se explica en las siguientes secciones:

Tema	Tarea
Configuración del clúster	1. Crea un clúster de GKE y habilita las funciones de instantáneas de Pod y federación de identidades para cargas de trabajo en GKE. 2. Implementa la zona de pruebas del agente.
Configura el almacenamiento y los permisos	1. Crea el bucket de Cloud Storage y la carpeta administrada. 2. Crea el rol de IAM personalizado. 3. Crea el espacio de nombres de Kubernetes y la cuenta de servicio de Kubernetes (KSA). 4. Vincula el rol de IAM a la cuenta de servicio de Kubernetes. 5. Otorga permisos al controlador de instantáneas.
Configura recursos de instantáneas	1. Crear `PodSnapshotStorageConfig` 2. Crea `PodSnapshotPolicy` 3. Crear `SandboxTemplate`

Configuración del clúster

Una app en zona de pruebas se ejecuta dentro de un Pod en un nodo del clúster de GKE, por lo que debes configurar un entorno de clúster. En esta sección, se muestra cómo crear un clúster de GKE y, luego, implementar el controlador de Agent Sandbox.

Crea un clúster de GKE

Crea un clúster de GKE Standard. Este clúster proporciona el entorno de Kubernetes en el que tomarás una instantánea de un entorno de Agent Sandbox. El siguiente comando crea el clúster y habilita la federación de identidades para cargas de trabajo para GKE y la función de instantáneas de Pods:

Para crear un clúster estándar con Google Cloud CLI, ejecuta el siguiente comando:

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

Además de crear el clúster, este comando habilita la federación de identidades para cargas de trabajo para GKE y la función de instantáneas de Pod en el clúster.

Recupera las credenciales del clúster para que la CLI de kubectl pueda conectarse a él. Este comando actualiza tu archivo de configuración de Kubernetes, que se almacena de forma predeterminada en el directorio ~/.kube/config. Este archivo de configuración contiene las credenciales que kubectl requiere para interactuar con tu clúster de GKE:
```
gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}
```

Crea un grupo de nodos con gVisor habilitado:

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

Este comando usa las siguientes marcas clave:

--image-type=cos_containerd: Especifica que los nodos usan Container-Optimized OS con containerd.
--sandbox type=gvisor: Habilita la tecnología de zona de pruebas de gVisor en los nodos, lo que se requiere para Agent Sandbox.

Implementa el controlador de Agent Sandbox en tu clúster

Puedes implementar el controlador de Agent Sandbox y sus componentes requeridos aplicando los manifiestos de la versión oficial a tu clúster. Estos manifiestos son archivos de configuración que le indican a Kubernetes que descargue todos los componentes necesarios para implementar y ejecutar el controlador de Agent Sandbox en tu clúster.

Para implementar Agent Sandbox en tu clúster de GKE, ejecuta el siguiente 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

Verifica el controlador

Después de aplicar los manifiestos, verifica que el Pod del controlador de Agent Sandbox se ejecute correctamente en el espacio de nombres agent-sandbox-system. Los manifiestos crearon automáticamente el espacio de nombres agent-sandbox-system cuando los aplicaste en el paso anterior.

kubectl get pods -n agent-sandbox-system

Espera a que el Pod muestre "Running" en la columna STATUS y "1/1" en la columna READY. Cuando el Pod se ejecuta correctamente, el resultado es similar al siguiente:

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

Ahora que el controlador de Agent Sandbox está en ejecución, puede crear y administrar automáticamente entornos de zona de pruebas para cualquier recurso Sandbox que crees en tu clúster.

Configura el almacenamiento y los permisos

En esta sección, se muestra cómo configurar el almacenamiento y los permisos necesarios para las instantáneas de Pod. Creas un bucket de Cloud Storage y una carpeta administrada para almacenar los datos de la instantánea. Luego, otorgas a tu zona de pruebas y al controlador de instantáneas los permisos que necesitan para acceder a ese almacenamiento.

Crea el bucket de Cloud Storage

Crea un bucket para almacenar tus instantáneas. Para garantizar que el proceso de instantáneas sea rápido y rentable, te recomendamos que crees el bucket con los siguientes parámetros de configuración:

Habilita los espacios de nombres jerárquicos: La función de espacios de nombres jerárquicos organiza tu bucket en una jerarquía de sistema de archivos en lugar de un espacio de nombres plano. Esta configuración permite una mayor capacidad de procesamiento de lectura y escritura y, en consecuencia, acelera el guardado y la restauración de instantáneas.
Inhabilita la eliminación no definitiva: La función de eliminación no definitiva protege los datos, ya que retiene los archivos borrados durante un período determinado. Sin embargo, el proceso de instantáneas crea y borra muchos archivos temporales durante la carga. Te recomendamos que inhabilites el borrado temporal para evitar cargos innecesarios por almacenar estos archivos temporales.

Para crear el bucket con estos parámetros de configuración, ejecuta el siguiente comando:

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

Crear una carpeta administrada

Crea una carpeta administrada para organizar las instantáneas en tu bucket. Las carpetas administradas te permiten aplicar permisos de IAM a una carpeta específica en lugar de a todo el bucket. Este acceso a nivel de carpeta limita el acceso de tu zona de pruebas solo a sus propias instantáneas y aísla esas instantáneas de otros datos del bucket.

Para crear una carpeta administrada, ejecuta este comando:

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

Configura la cuenta de servicio y los roles de IAM

Para permitir que GKE guarde instantáneas de forma segura, la cuenta de servicio de Kubernetes que usan los Pods que ejecutan tu carga de trabajo en zona de pruebas necesita permiso para escribir en tu bucket. Para otorgar este permiso, vincula roles de IAM Google Clouda la cuenta de servicio de Kubernetes que usan los Pods. En esta sección, se muestra cómo crear un rol personalizado de IAM, crear la cuenta de servicio de Kubernetes y configurar los permisos necesarios.

Crea un rol personalizado de IAM llamado podSnapshotGcsReadWriter que contenga los permisos necesarios para escribir datos de instantáneas:

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

Cuando el rol se crea correctamente, el resultado se ve de la siguiente manera:

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 el espacio de nombres en el que residirán tu zona de pruebas y su cuenta de servicio:
```
kubectl create namespace "${SNAPSHOT_NAMESPACE}"
```
Crea la cuenta de servicio de Kubernetes en el espacio de nombres que acabas de crear. En conjunto, la cuenta de servicio de Kubernetes y el espacio de nombres forman una identidad única que se usa para otorgar a tu zona de pruebas acceso seguro a los recursos de Google Cloud :
```
kubectl create serviceaccount "${SNAPSHOT_KSA_NAME}" \
    --namespace "${SNAPSHOT_NAMESPACE}"
```

Otorga el rol roles/storage.bucketViewer a todas las cuentas de servicio del espacio de nombres. Este rol permite que las cuentas vean los metadatos del bucket, pero no que lean ni escriban los datos en sí:

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"

Otorga tu rol podSnapshotGcsReadWriter personalizado a la cuenta de servicio de Kubernetes de tu zona de pruebas. Esta vinculación permite que solo esta cuenta específica escriba datos en la carpeta administrada:

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"

Otorga el rol roles/storage.objectUser a la cuenta de servicio de Kubernetes. Este rol es necesario para que el agente de instantáneas de Pod realice operaciones en carpetas administradas:

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"

Otorga permisos al controlador de instantáneas

Otorga el rol objectUser al controlador de instantáneas del sistema de GKE. Este permiso permite que el controlador administre el ciclo de vida de la instantánea, por ejemplo, borrar objetos de instantánea cuando borras un recurso 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 recursos de instantáneas

En esta sección, se muestra cómo configurar los recursos de instantáneas para tu carga de trabajo de Agent Sandbox.

Define el almacenamiento y las reglas de instantáneas

Para especificar dónde GKE guarda tus instantáneas y qué reglas rigen el proceso de instantáneas, debes crear dos recursos personalizados:

PodSnapshotStorageConfig: Este recurso especifica la ubicación del bucket y la carpeta de Cloud Storage en la que GKE guarda los archivos de instantáneas.
PodSnapshotPolicy: Este recurso define qué Pods son aptos para las instantáneas según sus etiquetas de Kubernetes. También especifica las reglas de activación, por ejemplo, si las instantáneas son manuales o se inician con la carga de trabajo del sandbox.

Para aplicar ambos recursos en un solo paso, ejecuta el siguiente comando en Cloud Shell. Este método ayuda a garantizar que las variables de entorno se inserten correctamente:

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

Verifica la configuración

Después de aplicar la configuración y la política de almacenamiento de instantáneas, verifica que los recursos estén listos para usarse. En esta sección, se muestra cómo verificar el estado de estos recursos personalizados.

Verifica el estado del recurso PodSnapshotStorageConfig:

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

El resultado debe contener una condición con type: Ready y status: "True":

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

Verifica el estado del recurso PodSnapshotPolicy:

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

El resultado debe contener una condición con type: Ready y status: "True". También debería indicar que se encontró el PodSnapshotStorageConfig al que se hace referencia:

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

Crea la plantilla de zona de pruebas

Ahora que las políticas y los permisos de almacenamiento están vigentes, crearás los recursos SandboxTemplate y SandboxClaim. Para que el proceso de instantáneas funcione, el entorno de pruebas debe ejecutarse con la cuenta de servicio de Kubernetes que creaste anteriormente en este documento. El entorno de pruebas también debe tener las etiquetas que especificaste anteriormente en PodSnapshotPolicy.

En este ejemplo, se usa una app de Python que imprime un contador incremental en los registros. Este contador te permite verificar que el estado se guarde correctamente y se restablezca más tarde.

Para crear los recursos SandboxTemplate y SandboxClaim, aplica el siguiente manifiesto:

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

Tu zona de pruebas ahora se ejecuta con la identidad correcta y está lista para crear una instantánea.

Crea una instantánea

En esta sección, se muestra cómo activar manualmente una instantánea de tu zona de pruebas en ejecución. Creas un recurso de activación que segmenta tu Pod de zona de pruebas y, luego, verificas que el proceso de instantáneas se complete correctamente.

Verifica los registros del contador inicial: Antes de activar la instantánea, consulta los registros del entorno de pruebas en ejecución para ver el valor actual del contador. Ver los registros establece un valor de referencia para comparar después de la restauración.
```
kubectl logs python-sandbox-example --namespace "${SNAPSHOT_NAMESPACE}" --tail=5
```
El resultado muestra las últimas líneas del contador, por ejemplo:
```
Count: 15
Count: 16
Count: 17
```
Observa los últimos valores de "Recuento" que se imprimieron.

Crea un recurso PodSnapshotManualTrigger: Inicia la instantánea:

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 que el activador manual se haya ejecutado correctamente:

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

El resultado debería mostrar el estado Complete, lo que indica que GKE activó correctamente la instantánea del Pod de destino:

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

Consulta más detalles sobre el estado capturado describiendo el activador:

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

El resultado contiene una sección Snapshot Created con el nombre único de los archivos de instantáneas almacenados en tu 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>

Restablece a partir de una instantánea

Después de capturar una instantánea, puedes restablecer el entorno de pruebas para reanudar la ejecución desde su estado guardado. Para restablecer el entorno de pruebas, crea un objeto SandboxClaim nuevo que haga referencia al objeto SandboxTemplate original. El controlador de instantáneas de Pod identifica y restablece automáticamente la instantánea coincidente más reciente.

Crea un nuevo SandboxClaim para restablecer la zona de pruebas:

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

Visualiza los registros para verificar que se haya realizado el restablecimiento. Ten en cuenta que el contador continúa desde el punto en el que se tomó la instantánea:
```
kubectl logs python-sandbox-from-snapshot --namespace "${SNAPSHOT_NAMESPACE}"
```
El resultado debería mostrar que se reanudó el contador, por ejemplo:
```
Count: 18
Count: 19
Count: 20
Count: 21
```

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este documento, sigue estos pasos para borrar los recursos que creaste:

Borra los reclamos de zona de pruebas para detener los Pods en ejecución y permitir que el controlador de la zona de pruebas del agente finalice los contenedores de forma ordenada.
```
kubectl delete sandboxclaims --all --namespace "${SNAPSHOT_NAMESPACE}"
```

Borra las plantillas de zona de pruebas y los activadores manuales que se usaron para crear zonas de pruebas y para iniciar instantáneas.

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

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

Borra las políticas de instantáneas que definen qué Pods son aptos para las instantáneas dentro de tu espacio de nombres.
```
kubectl delete podsnapshotpolicy cpu-psp --namespace "${SNAPSHOT_NAMESPACE}"
```
Borra la configuración de almacenamiento de instantáneas, que es la definición global de tu backend de almacenamiento de instantáneas. Como este recurso tiene alcance de clúster, no uses una marca de espacio de nombres.
```
kubectl delete podsnapshotstorageconfig cpu-pssc-gcs
```
Borra el espacio de nombres de Kubernetes para quitar automáticamente la cuenta de servicio de Kubernetes y los metadatos restantes con espacio de nombres.
```
kubectl delete namespace "${SNAPSHOT_NAMESPACE}"
```
Borra el clúster de GKE para quitar la infraestructura subyacente y todos los nodos asociados con el instructivo.
```
gcloud container clusters delete "${CLUSTER_NAME}" --location="${GKE_LOCATION}" --quiet
```
Borra el bucket de Cloud Storage (opcional) con el comando de eliminación recursiva si quieres restablecer por completo tu almacenamiento. Ten en cuenta que puedes omitir este paso si planeas volver a usar tu bucket configurado correctamente para pruebas futuras.
```
gcloud storage rm --recursive "gs://${SNAPSHOTS_BUCKET_NAME:?Error: SNAPSHOTS_BUCKET_NAME is not set. Please re-define the environment variables you defined earlier.}"
```
Borra el rol de IAM personalizado (opcional) si deseas que tu proyecto vuelva a un estado completamente limpio. Dado que los roles de IAM persisten incluso después de que se borra el clúster, debes borrarlos por separado.
```
gcloud iam roles delete podSnapshotGcsReadWriter --project="${PROJECT_ID}"
```

¿Qué sigue?

Obtén más información sobre las instantáneas de Pods de GKE.
Obtén más información sobre el proyecto de código abierto de Agent Sandbox en GitHub.
Obtén más información para aislar la ejecución de código de IA con Agent Sandbox.