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

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

Agent Sandbox en GKE mejora la seguridad, ya que proporciona un entorno 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 función es útil por los siguientes motivos:

  • Inicio rápido: Reduce el tiempo de inicio de la zona de pruebas restableciendo desde una instantánea precalentada.
  • Agentes de larga duración: Pausa una zona de pruebas que tarda mucho tiempo en ejecutarse y reanúdala más tarde, o muévela a un nodo diferente, sin perder el progreso.
  • Cargas de trabajo con estado: Conservan 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 varias zonas de pruebas nuevas con el mismo estado inicializado.

Una instantánea se puede activar de dos maneras:

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

En este documento, se muestra cómo activar una instantánea de forma manual.

Antes de comenzar

  1. En la consola de Google Cloud , en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud .

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
    • Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

    Ir al selector de proyectos

  2. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  3. Habilita las APIs de Google Kubernetes Engine, Cloud Storage, Identity and Access Management (IAM), si aún no están habilitadas.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar las API

  4. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

Requisitos

Las instantáneas de Pods de GKE requieren la versión 1.35.3-gke.1234000 o posterior de GKE. Se admiten los modos Autopilot y Standard.

Las instantáneas de Pods requieren gVisor y no funcionan con sandboxes de microVM.

Debido a que las instantáneas de Pods requieren GKE Sandbox, tu entorno está sujeto a ciertas limitaciones. Por ejemplo, las instantáneas de Pods 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.

Para obtener una lista completa de las restricciones, incluida la información sobre el uso de tipos de máquinas basados en GPU, 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 reutilizarlas 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 seguimiento del 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 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)")

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

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud actual. Los comandos de este documento usan este ID para nombrar recursos y otorgar permisos de IAM.
  • CLUSTER_NAME: Es el nombre de tu clúster de GKE (por ejemplo, agent-sandbox-cluster).
  • GKE_LOCATION: Es la región de Google Cloud para tu bucket de Cloud Storage (por ejemplo, us-central1). Si creas un clúster de Autopilot, el clúster también usará esta región.
  • ZONE: Es la zona del clúster de GKE. Si creas un clúster de Standard, configúralo en una zona de la región GKE_LOCATION (por ejemplo, us-central1-a). Para reducir los costos, en este documento se crea un clúster de Standard zonal.
  • AGENT_SANDBOX_VERSION: Es la versión del controlador de Agent Sandbox de código abierto que se instalará. En este documento, se usa la versión 1.0.6.
  • NODE_POOL_NAME: Es el nombre del grupo de nodos que ejecutará las cargas de trabajo de la 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 Pods 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 la carga de trabajo y la cuenta de servicio de la instantánea.
  • SNAPSHOT_KSA_NAME: Es el nombre de la cuenta de servicio de Kubernetes que usará tu carga de trabajo para autenticarse.
  • 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 Pods de Agent Sandbox en entornos de GKE, debes realizar algunos pasos de configuración. Para comprender estos pasos, es útil comprender primero algunos conceptos clave y, luego, el proceso de instantánea:

Conceptos clave

  • Entorno: Una aplicación de zona de pruebas se ejecuta dentro de un Pod de Kubernetes en un nodo del clúster de GKE.
  • Identidad: El Pod se asocia con una cuenta de servicio de Kubernetes y se ejecuta en un espacio de nombres especial que creas. Juntos, 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 las instantáneas se guarden en Cloud Storage, se deben otorgar permisos de IAM específicos a la identidad del Pod que le permitan escribir en un bucket de Cloud Storage.

Proceso de instantánea

  1. Activador: Se inicia una instantánea, ya sea de forma manual (externa) o por la carga de trabajo de la zona de pruebas. En este documento, se muestra un activador manual que inicias creando un recurso PodSnapshotManualTrigger.
  2. Captura: GKE captura el estado de ejecución del Pod, como el estado de la memoria del Pod y su sistema de archivos.
  3. Subida: Con los permisos otorgados a la cuenta de servicio de Kubernetes del Pod, GKE sube el estado capturado como archivos de instantánea 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 Autentica en las APIs deGoogle Cloud desde las cargas de trabajo de GKE.

Para habilitar las instantáneas de Pods de Agent Sandbox en entornos de GKE, realiza la siguiente configuración. Primero, prepara un entorno de clúster creando un clúster de GKE con Workload Identity Federation for GKE y las funciones de instantáneas de Pods habilitadas. Luego, configura las políticas de Cloud Storage y 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, crearás los recursos de instantánea que especifican la ubicación de almacenamiento y las políticas para 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 secciones que siguen:

Tema Tarea
Configuración del clúster 1. Crear un clúster de GKE y habilitar las funciones de instantáneas de Pods y de Workload Identity Federation for GKE.
2. Implementa Agent Sandbox.
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. Crea un recurso PodSnapshotStorageConfig
2. Crea un recurso PodSnapshotPolicy
3. Crea recursos SandboxTemplate, SandboxWarmPool y SandboxClaim

Configuración del clúster

Una app de zona de pruebas se ejecuta dentro de un Pod en un nodo de 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 nuevo que cumpla con los requisitos

Crea un clúster de GKE nuevo con las instantáneas de Pods habilitadas. Las instantáneas de Pods requieren la versión 1.35.3-gke.1234000 o posterior de GKE. Los siguientes comandos inscriben el clúster en el canal de versiones rápido, cuya versión predeterminada cumple con este requisito:

Autopilot

Crea un clúster de Autopilot con las funciones requeridas:

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

Estándar

Crea un clúster de Standard con las funciones requeridas. Para reducir los costos, el siguiente comando crea un clúster zonal, que ejecuta su plano de control y sus nodos en 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 grupo de nodos con GKE Sandbox habilitado. GKE Sandbox es una función de seguridad de contenedores basada en el proyecto de código abierto gVisor que proporciona una capa adicional de aislamiento entre las aplicaciones en ejecución y el 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 credenciales

Recupera las credenciales del clúster para que la CLI de kubectl pueda conectarse al clúster:

Autopilot 

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

Estándar 

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

Implementa el controlador de Agent Sandbox en tu clúster

Puedes implementar el controlador de Agent Sandbox y sus componentes necesarios aplicando el manifiesto de la versión oficial a tu clúster. Este manifiesto es un archivo de configuración que le indica 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 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

Para obtener más información sobre cómo instalar Agent Sandbox, consulta Instala Agent Sandbox en GKE.

Verifica el controlador

Después de aplicar el manifiesto, verifica que el Pod del controlador de Agent Sandbox se esté ejecutando correctamente en el espacio de nombres agent-sandbox-system. El manifiesto creó automáticamente el espacio de nombres agent-sandbox-system cuando lo aplicaste en el paso anterior.

kubectl get pods -n agent-sandbox-system

Espera a que el Pod muestre "En ejecución" en la columna ESTADO y "1/1" en la columna LISTO. Cuando el Pod se ejecuta de forma correcta, el resultado es similar al siguiente:

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

Ahora que el controlador de Agent Sandbox se está ejecutando, 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 Pods. Crea un bucket de Cloud Storage y una carpeta administrada para almacenar los datos de la instantánea. Luego, otorga a la 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ánea sea rápido y rentable, crea el bucket con la siguiente 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, por lo tanto, acelera el guardado y el restablecimiento de las instantáneas.
  • Inhabilitar la eliminación no definitiva: La función de eliminación no definitiva protege los datos reteniendo los archivos borrados durante un período establecido. Sin embargo, el proceso de instantánea crea y borra muchos archivos temporales durante la carga. Inhabilita la eliminación no definitiva 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}"

Crea una carpeta administrada

Crea una carpeta administrada para organizar las instantáneas dentro de 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 la zona de pruebas solo a sus propias instantáneas y las aísla 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 de zona de pruebas necesita permiso para escribir en tu bucket. Para otorgar este permiso, vincula los roles de IAM de Google Cloud a la cuenta de servicio de Kubernetes que usan los Pods. En esta sección, se muestra cómo crear un rol de IAM personalizado, crear la cuenta de servicio de Kubernetes y configurar los permisos necesarios.

  1. Crea un rol de IAM personalizado llamado podSnapshotGcsReadWriter que contenga los permisos necesarios para escribir datos de instantáneas. Si este rol ya existe en tu proyecto, por ejemplo, de una ejecución anterior de este documento, omite este paso. De lo contrario, ejecuta el siguiente comando:

    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

    Si el comando falla con un error FAILED_PRECONDITION que indica que el ID del rol se marcó para su eliminación, significa que borraste un rol con este ID recientemente, por ejemplo, en los pasos de limpieza de una ejecución anterior de este documento. IAM no te permite volver a usar ese ID durante un máximo de 37 días. Vuelve a ejecutar el comando con un ID de rol diferente, como podSnapshotGcsReadWriter2, y usa ese ID en lugar de podSnapshotGcsReadWriter en el resto de este documento.

  2. Crea el espacio de nombres en el que residirán la zona de pruebas y su cuenta de servicio:

    kubectl create namespace "${SNAPSHOT_NAMESPACE}"

  3. Crea la cuenta de servicio de Kubernetes en el espacio de nombres que acabas de crear. Juntos, 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}"

  4. Otorga el rol roles/storage.bucketViewer a todas las cuentas de servicio en el 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"

  5. Otorga tu rol personalizado de podSnapshotGcsReadWriter a la cuenta de servicio de Kubernetes para tu zona de pruebas. Esta vinculación permite que solo esta cuenta específica escriba datos en la carpeta administrada. Un rol personalizado nuevo puede tardar unos minutos en estar disponible, por lo que, si este comando falla porque el rol no existe, espera un minuto y, luego, vuelve a ejecutar el comando:

    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. 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 Pods realice operaciones en las 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, como 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 en GKE.

Define el almacenamiento y las reglas de las instantáneas

Para especificar dónde guarda GKE tus instantáneas y qué reglas rigen el proceso de creación de instantáneas, crea 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, como si las instantáneas son manuales o si las inicia la carga de trabajo de la zona de pruebas. En este ejemplo, se agrupan las instantáneas por la etiqueta agents.x-k8s.io/sandbox-name-hash, que el controlador de Agent Sandbox agrega al Pod de cada zona de pruebas. Esta agrupación significa que GKE restablece cada zona de pruebas solo a partir de sus propias instantáneas.

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

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

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.

  1. Verifica el estado del recurso PodSnapshotStorageConfig:

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

  2. 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 recurso 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 configurados, crea los recursos SandboxTemplate, SandboxWarmPool y SandboxClaim. El recurso SandboxWarmPool mantiene una zona de pruebas precalentada en ejecución, y el recurso SandboxClaim reclama esa zona de pruebas del grupo. Para que el proceso de instantánea funcione, la zona de pruebas debe ejecutarse con la cuenta de servicio de Kubernetes que creaste antes en este documento. La zona de pruebas también debe tener las etiquetas que especificaste antes en el recurso 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.

Autopilot

Las instantáneas de Pods no admiten tipos de máquinas E2. En Autopilot, es posible que GKE use de forma predeterminada tipos de máquinas que no admiten instantáneas de Pods. Para garantizar que tus cargas de trabajo se ejecuten en hardware compatible, debes usar una ComputeClass personalizada para priorizar las familias de máquinas compatibles.

  1. Guarda el siguiente manifiesto como 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. Aplica el manifiesto

    kubectl apply -f non-e2-class.yaml

  3. Para crear los recursos SandboxTemplate y SandboxWarmPool, aplica el siguiente manifiesto. Observa que el recurso SandboxTemplate hace referencia al ComputeClass que acabas de crear con el selector de nodos 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

Estándar

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

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

Después de crear los recursos, reclama una zona de pruebas del grupo de preparación:

  1. Espera hasta que la zona de pruebas del grupo de preparación esté lista:

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

  2. Crea un recurso SandboxClaim que reclame la zona de pruebas del grupo de preparación:

    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. Espera hasta que la reclamación esté lista y, luego, guarda el nombre de la zona de pruebas que usa la reclamación. El Pod de la zona de pruebas tiene el mismo nombre que la zona de pruebas:

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

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

Crea una instantánea

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

  1. Verifica los registros iniciales del contador: Antes de activar la instantánea, consulta los registros de la zona de pruebas en ejecución para ver el valor actual del contador. La visualización de los registros establece un modelo de referencia para comparar después de la restauración.

    kubectl logs "${SANDBOX_NAME}" --namespace "${SNAPSHOT_NAMESPACE}" --tail=5

    En el resultado, se muestran las últimas líneas del contador, por ejemplo:

    Count: 15
Count: 16
Count: 17

    Observa los últimos valores de "Count" que se imprimen.

  2. Crea un recurso PodSnapshotManualTrigger: Inicia la instantánea:

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

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

    El resultado debería mostrar un estado de 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-warmpool-x7k2p   Complete   XXs

  4. 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ánea 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 suspender la zona de pruebas para liberar sus recursos de procesamiento y, luego, reanudarla desde su estado guardado. Cuando suspendes una zona de pruebas, el controlador de Agent Sandbox borra el Pod de la zona de pruebas, pero conserva el recurso Sandbox. Cuando reanudas la zona de pruebas, el controlador vuelve a crear el Pod, y el controlador de instantáneas del Pod restablece automáticamente el Pod a partir de la instantánea más reciente de esa zona de pruebas.

  1. Espera hasta que la instantánea esté lista. GKE restablece un Pod solo desde una instantánea que está lista. Si suspendes la zona de pruebas antes de que la instantánea esté lista, la zona de pruebas se iniciará sin el estado guardado cuando la reanudes.

    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. Para suspender la zona de pruebas, establece su campo operatingMode en Suspended y, luego, espera hasta que el controlador borre el Pod de la zona de pruebas:

    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. Para reanudar la zona de pruebas, establece su campo operatingMode en Running y, luego, espera hasta que la zona de pruebas esté lista:

    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. Para verificar que se haya realizado el restablecimiento, consulta los registros. Ten en cuenta que el contador continúa desde el punto en el que se tomó la instantánea:

    kubectl logs "${SANDBOX_NAME}" --namespace "${SNAPSHOT_NAMESPACE}"

    El resultado debería mostrar que el contador se reanuda, por ejemplo:

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

    Si, en cambio, el contador comienza desde 0, el Pod se inició sin restablecerse desde la instantánea.

Limpia los recursos

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:

  1. Borra las reclamaciones de la zona de pruebas y los grupos de preparación para detener los Pods en ejecución y permitir que el controlador de Agent Sandbox finalice los contenedores de forma ordenada.

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

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

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

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

  3. Borra las políticas de instantáneas que definen qué Pods son aptos para instantáneas dentro de tu espacio de nombres.

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

  4. Borra la configuración de almacenamiento de instantáneas, que es la definición global de tu backend de almacenamiento de instantáneas. Debido a que este recurso tiene un permiso de clúster, no uses una marca de espacio de nombres.

    kubectl delete podsnapshotstorageconfig cpu-pssc-gcs

  5. Si creaste una para Autopilot, borra la ComputeClass.

    kubectl delete computeclass non-e2-class

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

  7. Borra el clúster de GKE para quitar la infraestructura subyacente y todos los nodos asociados con el instructivo.

    Autopilot 

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

    Estándar 

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

  8. 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 quieres volver a usar el 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.}"

  9. Borra el rol de IAM personalizado (opcional) si deseas devolver tu proyecto a un estado completamente limpio. Debido a que los roles de IAM persisten incluso después de borrar el clúster, debes borrarlos por separado.

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

¿Qué sigue?