Salvar e restaurar ambientes de sandbox do agente com snapshots de pod

Standard

Este documento é válido apenas para clusters Standard.

Este documento mostra como usar snapshots de pods do GKE para salvar o estado de um ambiente do Agent Sandbox em execução.

O sandbox do agente oferece um ambiente seguro e isolado para executar códigos não confiáveis, como os gerados por modelos de linguagem grandes (LLMs). Executar esse tipo de código diretamente em um cluster representa riscos de segurança, porque um código não confiável pode acessar ou interferir em outros apps ou no próprio nó do cluster.

Com os snapshots de pod do GKE, é possível salvar e restaurar o estado de ambientes em sandbox. Essa funcionalidade é útil pelos seguintes motivos:

Inicialização rápida: reduza o tempo de inicialização da sandbox restaurando de um snapshot pré-aquecido.
Agentes de longa duração: pause um sandbox que leva muito tempo para ser executado e retome-o mais tarde ou mova-o para um nó diferente sem perder o progresso.
Cargas de trabalho com estado: persistem o contexto de um agente, como o histórico de conversas ou cálculos intermediários, salvando e restaurando o estado do ambiente isolado.
Reprodução: capture um estado específico e use-o como base para iniciar várias novas caixas de sandbox com o mesmo estado inicializado.

Um snapshot pode ser acionado de duas maneiras:

Acionador manual:você cria um recurso PodSnapshotManualTrigger para acionar o snapshot.
Gatilho de carga de trabalho:o próprio aplicativo em sandbox sinaliza quando está pronto para ser salvo.

Neste documento, mostramos como acionar um snapshot manualmente.

Observação:os snapshots de pod do GKE são um recurso em pré-lançamento.

Antes de começar

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 snapshots de pod do GKE, você precisa de um cluster no modo Standard executando a versão 1.34.1-gke.3084001 ou mais recente do GKE. Recomendamos que você use o GKE versão 1.35 ou posterior. A versão 1.34 do GKE tem um problema conhecido em que o checkpointing pode falhar com um erro de entrada/saída relacionado a bugs de permissão do Cloud Storage.

Os snapshots de pod não são compatíveis com tipos de máquina E2. Como consequência, este tutorial cria um pool de nós com máquinas N2.

Se você quiser usar tipos de máquinas baseados em GPU para os nós no pool de nós, consulte Limitações e requisitos.

Definir variáveis de ambiente

Para simplificar os comandos executados neste documento, defina variáveis de ambiente no Cloud Shell. Essas variáveis armazenam valores como o ID do projeto Google Cloud , o nome do bucket do Cloud Storage que vai armazenar seus snapshots e o local do cluster do GKE.

Depois de definir essas variáveis, você pode reutilizá-las em vários comandos referenciando o nome da variável (por exemplo, $CLUSTER_NAME) em vez de digitar ou substituir valores a cada vez. Essa abordagem facilita o processo e reduz o risco de erros.

Para definir as seguintes variáveis de ambiente úteis no Cloud Shell, execute os comandos abaixo:

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

Confira uma explicação dessas variáveis de ambiente:

PROJECT_ID: o ID do seu projeto Google Cloud atual. Definir essa variável ajuda a garantir que todos os recursos, como seu cluster do GKE, sejam criados no projeto correto.
CLUSTER_NAME: o nome do cluster do GKE (por exemplo, agent-sandbox-cluster).
GKE_LOCATION: a região Google Cloud em que o cluster do GKE será criado (por exemplo, us-central1).
GKE_VERSION: a versão do cluster e do nó do GKE necessária para compatibilidade com snapshots de pod. Os snapshots de pod do GKE exigem a versão 1.34.1-gke.3084001 ou mais recente do GKE.
AGENT_SANDBOX_VERSION: a versão do controlador do sandbox do agente a ser implantada no cluster.
NODE_POOL_NAME: o nome do pool de nós que vai executar cargas de trabalho em sandbox (por exemplo, agent-sandbox-node-pool).
MACHINE_TYPE: o tipo de máquina dos nós no pool de nós (por exemplo, n2-standard-2). Os snapshots de pod não são compatíveis com tipos de máquina E2. Se você quiser usar tipos de máquinas baseados em GPU para os nós no pool de nós, consulte Limitações e requisitos. Para detalhes sobre diferentes séries de máquinas e como escolher entre as opções, consulte o Guia de comparação e recursos para famílias de máquinas.
SNAPSHOTS_BUCKET_NAME: o nome do bucket do Cloud Storage que você vai criar para armazenar snapshots.
SNAPSHOT_NAMESPACE: o namespace do Kubernetes em que sua carga de trabalho de snapshot e conta de serviço vão residir.
SNAPSHOT_KSA_NAME: o nome da conta de serviço do Kubernetes que sua carga de trabalho vai usar para autenticar.
SNAPSHOT_FOLDER: o diretório no bucket do Cloud Storage em que os snapshots serão organizados.
PROJECT_NUMBER: o identificador numérico exclusivo do projeto, usado para vinculações de permissão do IAM.

Visão geral das etapas de configuração

Para ativar snapshots de pods dos ambientes do Agent Sandbox, é necessário realizar algumas etapas de configuração. Para entender essas etapas, é útil primeiro conhecer alguns conceitos-chave e depois o processo de snapshot:

Principais conceitos

Ambiente:um aplicativo em sandbox é executado em um pod do Kubernetes em um nó de cluster do GKE.
Identidade:o pod está associado a uma conta de serviço do Kubernetes e é executado em um namespace especial que você cria. Juntos, a conta de serviço do Kubernetes e o namespace formam uma identidade exclusiva usada para conceder ao pod acesso seguro aos recursos do Google Cloud .
Permissões: para permitir que os snapshots sejam salvos no Cloud Storage, a identidade do pod precisa receber permissões específicas do IAM que permitam gravar em um bucket do Cloud Storage.

Processo de snapshot

Gatilho:um snapshot é iniciado manualmente (externamente) ou pela própria carga de trabalho em sandbox. Este documento demonstra um gatilho manual que você inicia criando um recurso PodSnapshotManualTrigger.
Captura:o GKE captura o estado de execução do pod, como o estado da memória e do sistema de arquivos dele.
Upload:usando as permissões concedidas à conta de serviço do Kubernetes do pod, o GKE faz upload do estado capturado como arquivos de snapshot para o bucket designado do Cloud Storage.

Para saber mais sobre como o GKE usa contas de serviço do Kubernetes e papéis do IAM para acessar recursos do Google Cloud , consulte Autenticar nas APIs do Google Cloud em cargas de trabalho do GKE.

Para ativar snapshots de pods de ambientes de sandbox do agente, faça a seguinte configuração. Primeiro, prepare um ambiente de cluster criando um cluster do GKE com a federação de identidade da carga de trabalho para GKE e os recursos de snapshots de pod ativados. Em seguida, configure o Cloud Storage e as políticas do IAM para garantir que seus snapshots sejam armazenados com segurança e que seu sandbox tenha as permissões necessárias. Por fim, crie os recursos de snapshot que especificam o local de armazenamento e as políticas da sua sandbox.

A tabela a seguir resume as etapas de configuração que você precisa realizar. Cada etapa é explicada nas seções a seguir:

Tópico	Tarefa
Configuração do cluster	1. Crie um cluster do GKE e ative os recursos de snapshots de pod e federação de identidade da carga de trabalho do GKE. 2. Implante o sandbox do agente.
Configurar armazenamento e permissões	1. Crie o bucket do Cloud Storage e a pasta gerenciada. 2. Crie o papel personalizado do IAM. 3. Crie o namespace e a conta de serviço do Kubernetes (KSA, na sigla em inglês). 4. Vincule o papel do IAM à conta de serviço do Kubernetes. 5. Conceda permissões ao controlador de snapshot.
Configurar recursos de snapshot	1. Crie `PodSnapshotStorageConfig` 2. Crie `PodSnapshotPolicy` 3. Criar `SandboxTemplate`

Configuração do cluster

Um app em sandbox é executado dentro de um pod em um nó de cluster do GKE. Portanto, é necessário configurar um ambiente de cluster. Nesta seção, mostramos como criar um cluster do GKE e implantar o controlador do sandbox do agente.

Criar um cluster do GKE

Crie um cluster do GKE Standard. Esse cluster fornece o ambiente do Kubernetes em que você vai criar um snapshot de um ambiente do Sandbox do agente. O comando a seguir cria o cluster e ativa a federação de identidade da carga de trabalho para GKE e o recurso de snapshots de pod:

Para criar um cluster Standard usando a Google Cloud CLI, execute o seguinte 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

Além de criar o cluster, esse comando ativa a federação de identidade da carga de trabalho para GKE e o recurso de snapshots de pod no cluster.

Recupere as credenciais do cluster para que a CLI kubectl possa se conectar a ele. Esse comando atualiza o arquivo de configuração do Kubernetes, que é armazenado por padrão no diretório ~/.kube/config. Esse arquivo de configuração contém as credenciais necessárias para que o kubectl interaja com seu cluster do GKE:
```
gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}
```

Crie um pool de nós com o gVisor ativado:

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

Esse comando usa as seguintes flags principais:

--image-type=cos_containerd: especifica que os nós usam o Container-Optimized OS com o containerd.
--sandbox type=gvisor: ativa a tecnologia de sandbox do gVisor nos nós, o que é necessário para o Agent Sandbox.

Implante o controlador do sandbox do agente no cluster

É possível implantar o controlador do Sandbox do agente e os componentes necessários aplicando os manifestos de lançamento oficiais ao cluster. Esses manifestos são arquivos de configuração que instruem o Kubernetes a baixar todos os componentes necessários para implantar e executar o controlador do Agent Sandbox no cluster.

Para implantar o Agent Sandbox no cluster do GKE, execute o seguinte 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

Verificar o controlador

Depois de aplicar os manifestos, verifique se o pod do controlador da sandbox do agente está sendo executado corretamente no namespace agent-sandbox-system. Os manifestos criaram automaticamente o namespace agent-sandbox-system quando você os aplicou na etapa anterior.

kubectl get pods -n agent-sandbox-system

Aguarde até que o pod mostre "Running" na coluna STATUS e "1/1" na coluna READY. Quando o pod estiver em execução corretamente, a saída será semelhante a esta:

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

Agora que o controlador do sandbox do agente está em execução, ele pode criar e gerenciar automaticamente ambientes em sandbox para qualquer recurso Sandbox que você criar no cluster.

Configurar armazenamento e permissões

Nesta seção, mostramos como configurar o armazenamento e as permissões necessárias para snapshots de pods. Você cria um bucket do Cloud Storage e uma pasta gerenciada para armazenar os dados do snapshot. Em seguida, conceda ao sandbox e ao controlador de snapshots as permissões necessárias para acessar esse armazenamento.

Criar o bucket do Cloud Storage

Crie um bucket para armazenar seus snapshots. Para garantir que o processo de criação de snapshots seja rápido e econômico, recomendamos que você crie o bucket com as seguintes configurações:

Ativar namespaces hierárquicos:o recurso de namespaces hierárquicos organiza seu bucket em uma hierarquia de sistema de arquivos em vez de um namespace simples. Essa configuração permite maior capacidade de leitura e gravação e, consequentemente, acelera o salvamento e a restauração de snapshots.
Desativar a exclusão reversível:esse recurso protege os dados retendo arquivos excluídos por um período definido. No entanto, o processo de snapshot cria e exclui muitos arquivos temporários durante o upload. Recomendamos que você desative a exclusão temporária para evitar cobranças desnecessárias pelo armazenamento desses arquivos temporários.

Para criar o bucket com essas configurações, execute o comando a seguir:

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

Criar uma pasta gerenciada

Crie uma pasta gerenciada para organizar snapshots no bucket. Com as pastas gerenciadas, é possível aplicar permissões do IAM a uma pasta específica em vez de a todo o bucket. Esse acesso no nível da pasta limita o acesso do sandbox apenas aos próprios snapshots e os isola de outros dados no bucket.

Para criar uma pasta gerenciada, execute este comando:

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

Configurar a conta de serviço e os papéis do IAM

Para permitir que o GKE salve snapshots com segurança, a conta de serviço do Kubernetes usada pelos pods que executam sua carga de trabalho em sandbox precisa de permissão para gravar no bucket. Para conceder essa permissão, vincule Google Cloud papéis do IAM à conta de serviço do Kubernetes usada pelos pods. Nesta seção, mostramos como criar um papel personalizado do IAM, criar a conta de serviço do Kubernetes e configurar as permissões necessárias.

Crie um papel personalizado do IAM chamado podSnapshotGcsReadWriter que contenha as permissões necessárias para gravar dados de snapshot:

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

Quando a função é criada com sucesso, a saída tem esta aparência:

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

Crie o namespace em que o sandbox e a conta de serviço vão residir:
```
kubectl create namespace "${SNAPSHOT_NAMESPACE}"
```
Crie a conta de serviço do Kubernetes no namespace que você acabou de criar. Juntos, a conta de serviço do Kubernetes e o namespace formam uma identidade exclusiva usada para conceder à sua sandbox acesso seguro aos recursos do Google Cloud :
```
kubectl create serviceaccount "${SNAPSHOT_KSA_NAME}" \
    --namespace "${SNAPSHOT_NAMESPACE}"
```

Conceda o papel roles/storage.bucketViewer a todas as contas de serviço no namespace. Com essa função, as contas podem ver os metadados do bucket, mas não ler nem gravar os dados em si:

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"

Conceda seu papel podSnapshotGcsReadWriter personalizado à conta de serviço do Kubernetes para seu sandbox. Essa vinculação permite que apenas essa conta específica grave dados na pasta gerenciada:

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"

Conceda o papel roles/storage.objectUser à conta de serviço do Kubernetes. Essa função é necessária para que o agente de snapshot do pod realize operações em pastas gerenciadas:

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"

Conceder permissões ao controlador de snapshot

Conceda o papel objectUser ao controlador de snapshots do sistema do GKE. Essa permissão permite que o controlador gerencie o ciclo de vida do snapshot, como a exclusão de objetos de snapshot quando você exclui um 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"

Configurar recursos de snapshot

Nesta seção, mostramos como configurar os recursos de snapshot para sua carga de trabalho do Agent Sandbox.

Definir armazenamento e regras de snapshots

Para especificar onde o GKE salva seus snapshots e quais regras regem o processo de snapshot, crie dois recursos personalizados:

PodSnapshotStorageConfig: esse recurso especifica o bucket do Cloud Storage e o local da pasta em que o GKE salva os arquivos de snapshot.
PodSnapshotPolicy: esse recurso define quais pods estão qualificados para snapshots com base nos rótulos do Kubernetes. Ele também especifica as regras de acionamento, como se os snapshots são manuais ou iniciados pela carga de trabalho do sandbox.

Para aplicar os dois recursos em uma etapa, execute o seguinte comando no Cloud Shell. Esse método ajuda a garantir que as variáveis de ambiente sejam injetadas corretamente:

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

Verificar a configuração

Depois de aplicar a configuração e a política de armazenamento de snapshots, verifique se os recursos estão prontos para uso. Esta seção mostra como verificar o status desses recursos personalizados.

Verifique o status do recurso PodSnapshotStorageConfig:

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

A saída precisa conter uma condição com type: Ready e status: "True":

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

Verifique o status do recurso PodSnapshotPolicy:

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

A saída precisa conter uma condição com type: Ready e status: "True". Ele também precisa indicar que o PodSnapshotStorageConfig referenciado foi encontrado:

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

Criar o modelo de sandbox

Agora que as políticas e permissões de armazenamento estão em vigor, crie os recursos SandboxTemplate e SandboxClaim. Para que o processo de snapshot funcione, a sandbox precisa ser executada com a conta de serviço do Kubernetes criada anteriormente neste documento. A sandbox também precisa ter os rótulos especificados anteriormente no PodSnapshotPolicy.

Este exemplo usa um app Python que imprime um contador crescente nos registros. Com esse contador, é possível verificar se o estado foi salvo e restaurado posteriormente.

Para criar os recursos SandboxTemplate e SandboxClaim, aplique o seguinte manifesto:

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

Sua sandbox agora está sendo executada com a identidade correta e está pronta para ser instantânea.

Criar um snapshot

Nesta seção, mostramos como acionar manualmente um snapshot da sua sandbox em execução. Você cria um recurso de gatilho que tem como destino o pod da sandbox e verifica se o processo de snapshot é concluído com sucesso.

Verifique os registros do contador inicial:antes de acionar o snapshot, confira os registros do sandbox em execução para ver o valor atual do contador. A visualização dos registros estabelece um valor de referência para comparar após a restauração.
```
kubectl logs python-sandbox-example --namespace "${SNAPSHOT_NAMESPACE}" --tail=5
```
A saída mostra as últimas linhas do contador, por exemplo:
```
Count: 15
Count: 16
Count: 17
```
Observe os últimos valores de "Count" impressos.

Crie um recurso PodSnapshotManualTrigger:inicie o snapshot:

kubectl apply -f - <<EOF
apiVersion: podsnapshot.gke.io/v1alpha1
kind: PodSnapshotManualTrigger
metadata:
  name: cpu-snapshot-trigger
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  targetPod: python-sandbox-example
EOF

Verifique se o gatilho manual foi bem-sucedido:

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

A saída precisa mostrar um status de Complete, indicando que o GKE acionou o snapshot do pod de destino:

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

Confira mais detalhes sobre o estado capturado descrevendo o acionador:

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

A saída contém uma seção Snapshot Created com o nome exclusivo dos arquivos de snapshot armazenados no seu 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>

Restaurar a partir de um snapshot

Depois de capturar um snapshot, é possível restaurar o ambiente de sandbox para retomar a execução do estado salvo. Para restaurar o sandbox, crie um novo SandboxClaim que faça referência ao SandboxTemplate original. O controlador de snapshot de pod identifica e restaura automaticamente o snapshot correspondente mais recente.

Crie um novo SandboxClaim para restaurar a sandbox:

kubectl apply -f - <<EOF
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: python-sandbox-from-snapshot
  namespace: ${SNAPSHOT_NAMESPACE}
  labels:
    app: agent-sandbox-workload
spec:
  sandboxTemplateRef:
    name: python-runtime-template
EOF

Confira os registros para verificar se a restauração foi realizada. O contador continua do ponto em que o snapshot foi tirado:
```
kubectl logs python-sandbox-from-snapshot --namespace "${SNAPSHOT_NAMESPACE}"
```
A saída vai mostrar a retomada do contador, por exemplo:
```
Count: 18
Count: 19
Count: 20
Count: 21
```

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste documento, siga as etapas abaixo para excluir os recursos criados:

Exclua as reivindicações de sandbox para interromper todos os pods em execução e permitir que o controlador do sandbox do agente encerre os contêineres sem problemas.
```
kubectl delete sandboxclaims --all --namespace "${SNAPSHOT_NAMESPACE}"
```

Exclua os modelos de sandbox e os acionadores manuais usados para criar sandboxes e iniciar snapshots.

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

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

Exclua as políticas de snapshot que definem quais pods estão qualificados para snapshots no seu namespace.
```
kubectl delete podsnapshotpolicy cpu-psp --namespace "${SNAPSHOT_NAMESPACE}"
```
Exclua a configuração de armazenamento de snapshots, que é a definição global do back-end de armazenamento de snapshots. Como esse recurso tem escopo de cluster, não use uma flag de namespace.
```
kubectl delete podsnapshotstorageconfig cpu-pssc-gcs
```
Exclua o namespace do Kubernetes para remover automaticamente a conta de serviço do Kubernetes e os metadados restantes do namespace.
```
kubectl delete namespace "${SNAPSHOT_NAMESPACE}"
```
Exclua o cluster do GKE para remover a infraestrutura subjacente e todos os nós associados ao tutorial.
```
gcloud container clusters delete "${CLUSTER_NAME}" --location="${GKE_LOCATION}" --quiet
```
Exclua o bucket do Cloud Storage (opcional) usando o comando de remoção recursiva se quiser redefinir totalmente o armazenamento. Você pode pular esta etapa se quiser reutilizar o bucket configurado corretamente para testes futuros.
```
gcloud storage rm --recursive "gs://${SNAPSHOTS_BUCKET_NAME:?Error: SNAPSHOTS_BUCKET_NAME is not set. Please re-define the environment variables you defined earlier.}"
```
Exclua o papel personalizado do IAM (opcional) se quiser retornar o projeto a um estado completamente limpo. Como as funções do IAM permanecem mesmo depois que o cluster é excluído, elas precisam ser excluídas separadamente.
```
gcloud iam roles delete podSnapshotGcsReadWriter --project="${PROJECT_ID}"
```

A seguir

Saiba mais sobre os snapshots de pods do GKE.
Saiba mais sobre o projeto de código aberto do Agent Sandbox no GitHub.
Saiba como isolar a execução de código de IA com o Agent Sandbox.