Acionar snapshots do sandbox do agente de dentro de um cluster

Autopilot Padrão

Use snapshots do sandbox do agente em um cluster do Google Kubernetes Engine (GKE) para preservar o estado dos ambientes em sandbox. Essa abordagem oferece depuração consistente, acelera a iteração de desenvolvimento e facilita a recuperação rápida de configurações complexas. Neste tutorial, você vai implantar e testar esse recurso executando um aplicativo cliente que cria, pausa e retoma ambientes em sandbox de maneira programática dentro do cluster.

Para mais informações sobre como criar snapshots de pods, consulte Restaurar de um snapshot de pod.

Custos

O sandbox do agente é oferecido sem custo extra no GKE. Os preços do GKE são aplicados aos recursos criados.

Antes de começar

1. No Google Cloud console do, na página do seletor de projetos, escolha ou crie um Google Cloud projeto do.

   Funções necessárias para selecionar ou criar um projeto

   • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
   • Criar um projeto: para criar um projeto, é necessário ter o papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.
   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

2. Verifique se o faturamento está ativado para o Google Cloud projeto.

3. Ative as APIs Artifact Registry, Kubernetes Engine e Cloud Build.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, você pode receber essa permissão pelo papel de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar as APIs

4. No Google Cloud console do, ative o Cloud Shell.

   Ativar o Cloud Shell

5. Verifique se você tem as permissões necessárias para concluir este tutorial.

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar sandboxes, peça ao administrador para conceder a você o papel do IAM de administrador do Kubernetes Engine (roles/container.admin) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Limitações

Em um cluster regional, os nós em diferentes zonas podem ter microarquiteturas de CPU diferentes. Como os snapshots capturam o estado da CPU, a restauração de um snapshot em um nó com recursos de CPU ausentes falha (por exemplo, com o erro OCI runtime restore failed: incompatible FeatureSet).

Para evitar esse problema, use a configuração adequada para seu ambiente:

• Produção: para preservar a alta disponibilidade no cluster, não fixe cargas de trabalho em uma zona específica. Em vez disso, ajude a garantir a consistência dos recursos da CPU em todas as zonas especificando uma plataforma de CPU mínima. Para mais informações, consulte Escolher uma plataforma mínima de CPU.
• Teste: para simplificar a configuração e evitar erros iniciais de incompatibilidade de CPU, você pode usar um campo nodeSelector no manifesto SandboxTemplate para fixar o pod em uma zona específica, como us-central1-a. O exemplo neste tutorial usa essa configuração de teste.

Definir as variáveis de ambiente

Para simplificar os comandos executados neste tutorial, defina variáveis de ambiente no Cloud Shell. No Cloud Shell, defina as seguintes variáveis de ambiente úteis executando os comandos a seguir:

export PROJECT_ID=$(gcloud config get project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export CLUSTER_NAME="test-snapshot"
export LOCATION="us-central1"
export BUCKET_LOCATION="us"
export MACHINE_TYPE="n2-standard-2"
export REPOSITORY_NAME="agent-sandbox"
export BUCKET_NAME="${PROJECT_ID}_snapshots"
export CLOUDBUILD_BUCKET_NAME="${PROJECT_ID}_cloudbuild"

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

• PROJECT_ID: o ID do projeto Google Cloud atual. A definição dessa variável ajuda a garantir que todos os recursos sejam criados no projeto correto.
• PROJECT_NUMBER: o número do projeto atual. Google Cloud
• CLUSTER_NAME: o nome do cluster do GKE, por exemplo, test-snapshot.
• LOCATION: a Google Cloud região em que o cluster do GKE e o repositório do Artifact Registry estão localizados, por exemplo, us-central1.
• BUCKET_LOCATION: o local dos buckets do Cloud Storage, por exemplo, us.
• BUCKET_NAME: o nome do bucket do Cloud Storage usado para snapshots.
• CLOUDBUILD_BUCKET_NAME: o nome do bucket do Cloud Storage usado para registros do Cloud Build.
• MACHINE_TYPE: o tipo de máquina a ser usado para os nós do cluster, por exemplo, e2-standard-8.
• REPOSITORY_NAME: o nome do repositório do Artifact Registry, por exemplo, agent-sandbox.

Visão geral das etapas de configuração

Para ativar e testar snapshots de pods de ambientes do sandbox do agente no cluster, é necessário realizar várias etapas de configuração. Para entender essas etapas, é útil primeiro entender os componentes envolvidos no fluxo de trabalho geral.

Principais componentes

Este tutorial usa os dois aplicativos Python a seguir para testar o processo de snapshot:

• Aplicativo cliente: um script Python em execução em um pod padrão no cluster. Esse aplicativo gerencia o ciclo de vida do sandbox: ele cria o sandbox de maneira programática, pausa para acionar um snapshot, retoma o sandbox e verifica se o estado foi preservado. Neste tutorial, você vai criar uma conta de serviço do Kubernetes chamada agent-sandbox-client-sa e conceder permissões de RBAC para que o pod do aplicativo cliente possa gerenciar recursos personalizados do sandbox e objetos de acionador de snapshot usando a API Kubernetes.
• Aplicativo em sandbox: um script Python que incrementa e imprime um contador a cada segundo. Esse aplicativo é executado com segurança no ambiente de sandbox isolado para gerar um estado de mudança que o aplicativo cliente pode verificar. Neste tutorial, você vai criar uma conta de serviço dedicada do Kubernetes chamada snapshot-sa e configurar a Identidade da carga de trabalho para autorizar o pod em sandbox a ler e gravar objetos de snapshot com segurança no Cloud Storage.

Processo de configuração e teste

A lista a seguir resume as etapas necessárias para configurar o ambiente e executar o teste:

1. Criar um cluster: crie um cluster do Autopilot ou Standard com snapshots de pods e o recurso de sandbox do agente ativado.
2. Criar um repositório do Artifact Registry: crie um repositório do Docker para armazenar a imagem de contêiner do aplicativo cliente.
3. Instalar o sandbox do agente: instale os componentes e extensões principais do sandbox do agente no cluster.
4. Configurar armazenamento e permissões: crie um bucket do Cloud Storage e configure as permissões da Identidade da carga de trabalho para permitir que os snapshots sejam salvos com segurança.
5. Configurar snapshots de pods: crie e aplique a configuração de armazenamento de snapshots, a política de snapshots e o modelo de sandbox.
6. Criar o aplicativo cliente: crie a imagem de contêiner do aplicativo cliente e envie-a para o repositório do Artifact Registry.
7. Executar o teste: implante o pod do aplicativo cliente, que cria o sandbox, pausa para capturar um snapshot, retoma e verifica se o estado do contador foi restaurado.

Criar um cluster

Crie um novo cluster do GKE com snapshots de pods ativados. Para compatibilidade total de recursos, especifique o canal de lançamento rápido.

Autopilot

Crie um cluster do Autopilot com os recursos necessários:

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

Padrão

Crie um cluster padrão com os recursos necessários:

gcloud beta container clusters create ${CLUSTER_NAME} \
   --enable-pod-snapshots \
   --release-channel=rapid \
   --machine-type=${MACHINE_TYPE} \
   --workload-pool=${PROJECT_ID}.svc.id.goog \
   --workload-metadata=GKE_METADATA \
   --num-nodes=1 \
   --location=${LOCATION}

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

gcloud container node-pools create gvisor-pool \
   --cluster ${CLUSTER_NAME} \
   --num-nodes=1 \
   --location=${LOCATION} \
   --project=${PROJECT_ID} \
   --sandbox type=gvisor

Criar um repositório do Artifact Registry

Crie um repositório do Docker no Artifact Registry para armazenar a imagem de contêiner do aplicativo cliente (o aplicativo que cria e gerencia o sandbox):

gcloud artifacts repositories create ${REPOSITORY_NAME} \
   --repository-format=docker \
   --location=${LOCATION} \
   --description="Docker repository for Agent Sandbox"

Instalar o sandbox do agente

Observação: para oferecer suporte ao fluxo de trabalho de suspensão e retomada de snapshots, este tutorial usa um método de instalação manual para implantar os componentes do sandbox do agente diretamente do repositório de código aberto do GitHub. Essa instalação manual é uma solução alternativa temporária até que os recursos de snapshot estejam totalmente disponíveis no complemento do sandbox do agente do GKE.

Instale os componentes e extensões principais do sandbox do agente no cluster (usando a versão v0.4.6 como exemplo):

# Install the core agent-sandbox components
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.4.6/manifest.yaml

# Install the extensions (e.g., Warm Pools, Claims)
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.4.6/extensions.yaml

Configurar armazenamento e permissões

Configure um bucket do Cloud Storage para armazenar snapshots de pods e conceda as permissões necessárias da Identidade da carga de trabalho à conta de serviço snapshot-sa e ao agente de serviço do GKE. Isso permite que as cargas de trabalho em sandbox salvem e recuperem objetos de snapshot com segurança:

1. Crie um novo bucket do Cloud Storage

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

2. Crie uma conta de serviço do Kubernetes no namespace default. O aplicativo em sandbox (o script de contador do Python) usa essa identidade para autenticar APIs externas e acessar objetos de snapshot armazenados no Cloud Storage com segurança:

   kubectl create serviceaccount "snapshot-sa" \
       --namespace "default"
   

3. Vincule o papel storage.bucketViewer à sua conta de serviço usando a Identidade da carga de trabalho. Esse papel permite que a carga de trabalho em sandbox liste o conteúdo do bucket e localize snapshots específicos:

   gcloud storage buckets add-iam-policy-binding "gs://${BUCKET_NAME}" \
       --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/default/sa/snapshot-sa" \
       --role="roles/storage.bucketViewer"
   

4. Vincule o papel storage.objectUser à sua conta de serviço usando a Identidade da carga de trabalho. Esse papel fornece a permissão para ler, salvar e excluir objetos binários de snapshot no bucket:

   gcloud storage buckets add-iam-policy-binding "gs://${BUCKET_NAME}" \
       --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/default/sa/snapshot-sa" \
       --role="roles/storage.objectUser"
   

5. Conceda permissões ao agente de serviço do GKE para gerenciar (criar, listar, ler e excluir) objetos de snapshot no bucket:

   gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
       --member="serviceAccount:service-${PROJECT_NUMBER}@container-engine-robot.iam.gserviceaccount.com" \
       --role="roles/storage.objectUser" \
       --condition="expression=resource.name.startsWith(\"projects/_/buckets/${BUCKET_NAME}\"),title=restrict_to_bucket,description=Restricts access to one bucket only"
   

Configurar snapshots de pods

Crie e aplique os arquivos de configuração para instalar os recursos personalizados necessários do Kubernetes. Esses recursos definem como o cluster armazena e gerencia snapshots de pods:

• PodSnapshotStorageConfig: especifica o bucket do Cloud Storage designado para armazenar objetos binários de snapshot.
• PodSnapshotPolicy: define como os snapshots são acionados manualmente, com que frequência são agrupados e as políticas de retenção.
• SandboxTemplate: define o contêiner subjacente, os seletores de nós e as contas de serviço para executar a carga de trabalho isolada em sandbox.

1. Crie um novo diretório para os arquivos do cliente de teste:

   mkdir test_client
   

2. Navegue até o novo diretório:

   cd test_client
   

3. Crie um arquivo chamado snapshot_storage_config.yaml. Essa configuração especifica o bucket de destino do Cloud Storage em que o cluster salva o estado binário do snapshot do pod:

   apiVersion: podsnapshot.gke.io/v1
   kind: PodSnapshotStorageConfig
   metadata:
     name: example-pod-snapshot-storage-config
   spec:
     snapshotStorageConfig:
       gcs:
         bucket: "$BUCKET_NAME"
   

4. Substitua o marcador de posição da variável de ambiente no arquivo de configuração:

   sed -i "s/\$BUCKET_NAME/$BUCKET_NAME/g" snapshot_storage_config.yaml
   

5. Aplique o manifesto de configuração de armazenamento:

   kubectl apply -f snapshot_storage_config.yaml
   

6. Aguarde a configuração de armazenamento ficar pronta:

   kubectl wait --for=condition=Ready podsnapshotstorageconfig/example-pod-snapshot-storage-config --timeout=60s
   

7. Crie um arquivo chamado snapshot_policy.yaml. Essa configuração estabelece uma regra de retenção que mantém um máximo de dois snapshots para a carga de trabalho em sandbox. O tipo de acionador é definido como manual: isso permite que o aplicativo cliente controle snapshots sob demanda:

   apiVersion: podsnapshot.gke.io/v1
   kind: PodSnapshotPolicy
   metadata:
     name: example-pod-snapshot-policy
     namespace: default
   spec:
     storageConfigName: example-pod-snapshot-storage-config
     selector:
       matchLabels:
         app: agent-sandbox-workload
     triggerConfig:
       type: manual
       postCheckpoint: resume
     snapshotGroupingRules:
       groupByLabelValue:
         labels: ["agents.x-k8s.io/sandbox-name-hash", "tenant-id", "user-id"]
         groupRetentionPolicy:
           maxSnapshotCountPerGroup: 2
   

8. Aplique o manifesto da política de snapshot:

   kubectl apply -f snapshot_policy.yaml
   

9. Crie um arquivo chamado python-counter-template.yaml. Essa configuração define o pod do sandbox e atribui a identidade da conta de serviço snapshot-sa a ele. Essa atribuição ajuda a garantir que o sandbox seja executado com segurança. Dentro desse pod, o aplicativo em sandbox (um script Python) imprime continuamente um contador crescente nos registros do contêiner:

   apiVersion: extensions.agents.x-k8s.io/v1alpha1
   kind: SandboxTemplate
   metadata:
     name: python-counter-template
     namespace: default
   spec:
     podTemplate:
       metadata:
         labels:
           app: agent-sandbox-workload
       spec:
         serviceAccountName: snapshot-sa
         runtimeClassName: gvisor
         nodeSelector:
           topology.kubernetes.io/zone: us-central1-a # Pin to a zone to avoid CPU mismatch during restore
         containers:
         - name: python-counter
           image: python:3.13-slim
           command: ["python3", "-c"]
           args:
             - |
               import time
               i = 0
               while True:
                 print(f"Count: {i}", flush=True)
                 i += 1
                 time.sleep(1)
   

10. Aplique o manifesto do modelo de sandbox:

    kubectl apply -f python-counter-template.yaml
    

Criar o aplicativo cliente

Crie a imagem do contêiner do aplicativo cliente e faça upload dela no Artifact Registry.

1. Crie um arquivo chamado Dockerfile.client. Esse arquivo define o ambiente de execução e as dependências do Python para o aplicativo cliente:

   FROM python:3.13-slim
   
   WORKDIR /app
   
   RUN pip install "k8s-agent-sandbox[tracing]==0.4.6"
   
   # Copy test script
   COPY client_test.py /app/client_test.py
   
   CMD ["python", "/app/client_test.py"]
   

2. Crie um arquivo chamado client_test.py. Esse script gerencia o ciclo de vida do sandbox e verifica se o estado é retomado após a criação de um snapshot:

   import time
   import logging
   import re
   from kubernetes import config, client
   from k8s_agent_sandbox.gke_extensions.snapshots import PodSnapshotSandboxClient
   
   logging.basicConfig(level=logging.INFO)
   
   def get_last_count(pod_name, namespace):
       v1 = client.CoreV1Api()
       try:
           logs = v1.read_namespaced_pod_log(name=pod_name, namespace=namespace)
           counts = re.findall(r"Count: (\d+)", logs)
           if counts:
               return int(counts[-1])
           return None
       except Exception as e:
           logging.error(f"Failed to read logs for pod {pod_name}: {e}")
           return None
   
   def get_current_pod_name(sandbox_id, namespace):
       custom_api = client.CustomObjectsApi()
       try:
           sandbox_cr = custom_api.get_namespaced_custom_object(
               group="agents.x-k8s.io",
               version="v1alpha1",
               namespace=namespace,
               plural="sandboxes",
               name=sandbox_id
           )
           metadata = sandbox_cr.get("metadata", {})
           annotations = metadata.get("annotations", {})
           return annotations.get("agents.x-k8s.io/pod-name")
       except Exception as e:
           logging.error(f"Failed to get sandbox CR: {e}")
           return None
   
   def get_current_count(sandbox_id, namespace="default"):
       pod_name = get_current_pod_name(sandbox_id, namespace)
       if not pod_name:
           logging.error(f"Could not determine pod name for sandbox {sandbox_id}")
           return None
       return get_last_count(pod_name, namespace)
   
   def suspend_sandbox(sandbox):
       logging.info("Pausing sandbox (using snapshots)...")
       try:
           suspend_resp = sandbox.suspend(snapshot_before_suspend=True)
           if suspend_resp.success:
               logging.info("Sandbox paused successfully.")
               if suspend_resp.snapshot_response:
                   logging.info(f"Snapshot created: {suspend_resp.snapshot_response.snapshot_uid}")
               return suspend_resp
           else:
               logging.error(f"Failed to pause: {suspend_resp.error_reason}")
               exit(1)
       except Exception as e:
           logging.error(f"Failed to pause sandbox: {e}")
           exit(1)
   
   def resume_sandbox(sandbox):
       logging.info("Resuming sandbox (using snapshots)...")
       try:
           resume_resp = sandbox.resume()
           if resume_resp.success:
               logging.info("Sandbox resumed successfully.")
               if resume_resp.restored_from_snapshot:
                   logging.info(f"Restored from snapshot: {resume_resp.snapshot_uid}")
               return resume_resp
           else:
               logging.error(f"Failed to resume: {resume_resp.error_reason}")
               exit(1)
       except Exception as e:
           logging.error(f"Failed to resume sandbox: {e}")
           exit(1)
   
   def verify_continuity(count_before, count_after):
       if count_before is not None and count_after is not None:
           logging.info(f"Verification: Count before={count_before}, Count after={count_after}")
           if count_after >= count_before:
               logging.info("SUCCESS: Sandbox resumed from where it left off (or later).")
           else:
               logging.error("FAIL: Sandbox counter reset or went backwards!")
       else:
           logging.warning("Could not verify counter continuity.")
   
   def main():
       try:
           config.load_incluster_config()
       except config.ConfigException:
           config.load_kube_config()
   
       client_reg = PodSnapshotSandboxClient()
   
       logging.info("Creating sandbox...")
       sandbox = client_reg.create_sandbox(template="python-counter-template", namespace="default")
       logging.info(f"Sandbox created with ID: {sandbox.sandbox_id}")
   
       logging.info("Waiting for sandbox to run...")
       time.sleep(10)
   
       count_before = get_current_count(sandbox.sandbox_id)
       logging.info(f"Count before suspend: {count_before}")
   
       suspend_sandbox(sandbox)
   
       logging.info("Waiting 10 seconds...")
       time.sleep(10)
   
       resume_sandbox(sandbox)
   
       logging.info("Waiting for sandbox to be ready again...")
       time.sleep(10)
   
       count_after = get_current_count(sandbox.sandbox_id)
       logging.info(f"Count after resume: {count_after}")
   
       verify_continuity(count_before, count_after)
   
       logging.info("Snapshot test completed successfully.")
   
   if __name__ == "__main__":
       main()
   

3. Crie a imagem do contêiner do cliente e faça upload dela no Artifact Registry. Se o ambiente (como o Cloud Shell) tiver o Docker instalado, você poderá usar o Docker para criar a imagem localmente. Se você estiver trabalhando em um ambiente sem o Docker, poderá usar o Cloud Build para criar e enviar a imagem remotamente:

   Docker

   1. Configure a autenticação do Docker para o Artifact Registry:

      gcloud auth configure-docker "${LOCATION}-docker.pkg.dev"
      

   2. Crie e envie a imagem do contêiner do cliente localmente:

      docker build -t "${LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY_NAME}/sandbox-client:latest" -f Dockerfile.client .
      docker push "${LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY_NAME}/sandbox-client:latest"
      

   Cloud Build

   1. Crie um arquivo chamado cloudbuild.yaml:

      steps:
      - name: 'gcr.io/cloud-builders/docker'
        args: ['build', '-t', '$LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY_NAME/sandbox-client:latest', '-f', 'Dockerfile.client', '.']
      images:
      - '$LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY_NAME/sandbox-client:latest'
      

   2. Substitua os marcadores de posição da variável de ambiente no arquivo de configuração:

      sed -i "s/\$REPOSITORY_NAME/$REPOSITORY_NAME/g" cloudbuild.yaml
      sed -i "s/\$LOCATION/$LOCATION/g" cloudbuild.yaml
      sed -i "s/\$PROJECT_ID/$PROJECT_ID/g" cloudbuild.yaml
      

   3. Crie o bucket do Cloud Storage para registros do Cloud Build:

      gcloud storage buckets create "gs://${CLOUDBUILD_BUCKET_NAME}" \
          --location="${BUCKET_LOCATION}"
      

   4. Conceda as permissões necessárias à conta de serviço do Cloud Build.

      Os comandos a seguir usam a conta de serviço padrão do Compute Engine ($[e-mail]), que é a padrão para a maioria dos projetos. Se o projeto usar a conta de serviço legada do Cloud Build, substitua o endereço de e-mail do membro nos comandos a seguir por $[e-mail].

      Como você adicionou uma vinculação condicional do IAM ao projeto anteriormente neste tutorial, inclua a flag --condition=None ao adicionar essas novas vinculações. Isso impede que o gcloud pause para pedir confirmação interativa:

      gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member="serviceAccount:$[e-mail]" \
         --role="roles/artifactregistry.writer"
      
      gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member="serviceAccount:$[e-mail]" \
         --role="roles/logging.logWriter"
      
      gcloud storage buckets add-iam-policy-binding "gs://$CLOUDBUILD_BUCKET_NAME" \
         --member="serviceAccount:$[e-mail]" \
         --role="roles/storage.objectAdmin"
      

   5. Execute a build usando o Cloud Build:

      gcloud builds submit --config cloudbuild.yaml
      

Executar o teste

Implante o aplicativo cliente para criar o sandbox, acionar um snapshot e verificar se o contador interno é retomado com sucesso do estado salvo.

1. Crie um arquivo chamado client_sa.yaml. Esse manifesto define a conta de serviço agent-sandbox-client-sa e as permissões de RBAC necessárias para gerenciar recursos personalizados do sandbox:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: agent-sandbox-client-sa
     namespace: default
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: agent-sandbox-client-role
     namespace: default
   rules:
   - apiGroups: ["agents.x-k8s.io"]
     resources: ["sandboxes"]
     verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
   - apiGroups: ["extensions.agents.x-k8s.io"]
     resources: ["sandboxclaims"]
     verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
   - apiGroups: ["podsnapshot.gke.io"]
     resources: ["podsnapshotmanualtriggers", "podsnapshots"]
     verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
   - apiGroups: [""]
     resources: ["pods", "pods/log"]
     verbs: ["get", "list", "watch"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: agent-sandbox-client-rolebinding
     namespace: default
   subjects:
   - kind: ServiceAccount
     name: agent-sandbox-client-sa
     namespace: default
   roleRef:
     kind: Role
     name: agent-sandbox-client-role
     apiGroup: rbac.authorization.k8s.io
   

2. Aplique a conta de serviço do cliente e o manifesto do RBAC:

   kubectl apply -f client_sa.yaml
   

3. Crie um arquivo chamado client_pod.yaml. Esse manifesto cria o pod do aplicativo cliente usando a imagem de contêiner pré-criada:

   apiVersion: v1
   kind: Pod
   metadata:
     name: agent-sandbox-client-pod
     namespace: default
   spec:
     serviceAccountName: agent-sandbox-client-sa
     containers:
     - name: client
       image: $LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY_NAME/sandbox-client:latest
       imagePullPolicy: Always
     restartPolicy: Never
   

4. Substitua os marcadores de posição da variável de ambiente no manifesto:

   sed -i "s/\$REPOSITORY_NAME/$REPOSITORY_NAME/g" client_pod.yaml
   sed -i "s/\$LOCATION/$LOCATION/g" client_pod.yaml
   sed -i "s/\$PROJECT_ID/$PROJECT_ID/g" client_pod.yaml
   

5. Aplique o manifesto do pod do aplicativo cliente:

   kubectl apply -f client_pod.yaml
   

6. Transmita os registros do pod para verificar o fluxo de execução:

   kubectl logs -f agent-sandbox-client-pod
   

Quando o teste estiver em execução corretamente, a saída será semelhante a esta (abreviada aqui para facilitar a leitura):

2026-04-21 23:02:39,030 - INFO - Creating sandbox...
...
2026-04-21 23:02:51,755 - INFO - Count before suspend: 23
2026-04-21 23:02:51,755 - INFO - Pausing sandbox (using snapshots)...
...
2026-04-21 23:03:07,115 - INFO - Resuming sandbox (using snapshots)...
...
2026-04-21 23:03:21,329 - INFO - Count after resume: 38
2026-04-21 23:03:21,329 - INFO - Verification: Count before=23, Count after=38
2026-04-21 23:03:21,329 - INFO - SUCCESS: Sandbox resumed from where it left off (or later).

A saída mostra que o sandbox preserva o estado quando suspenso e retomado. O contador para de avançar enquanto o sandbox está suspenso (pausado e dimensionado para zero) e retoma o contador quando o sandbox é restaurado. Sem suspender, o contador teria continuado avançando durante o período de suspensão e a contagem seria significativamente maior.

Limpar recursos

Para evitar cobranças na sua Google Cloud conta do, exclua os recursos criados:

1. Exclua o cluster do GKE. Isso também exclui o pool de nós e todas as contas de serviço do Kubernetes nele:

   gcloud beta container clusters delete ${CLUSTER_NAME} --location="${LOCATION}" --quiet
   

2. Exclua o repositório do Artifact Registry para remover o repositório do Docker criado para a imagem de teste:

   gcloud artifacts repositories delete ${REPOSITORY_NAME} --location="${LOCATION}" --quiet
   

3. Exclua o bucket do Cloud Storage e todos os snapshots nele. Isso remove automaticamente as vinculações do IAM da Identidade da carga de trabalho no nível do bucket aplicadas a ele:

   gcloud storage rm --recursive "gs://${BUCKET_NAME}"
   

4. Remova a vinculação do IAM para envolvidos no projeto para o agente de serviço do GKE:

   gcloud projects remove-iam-policy-binding "${PROJECT_ID}" \
       --member="serviceAccount:service-${PROJECT_NUMBER}@container-engine-robot.iam.gserviceaccount.com" \
       --role="roles/storage.objectUser" \
       --condition="expression=resource.name.startsWith(\"projects/_/buckets/${BUCKET_NAME}\"),title=restrict_to_bucket,description=Restricts access to one bucket only"
   

5. Se você usou o Cloud Build em vez do Docker para criar e enviar a imagem de contêiner, exclua o bucket de registros e remova as permissões da conta de serviço:

   gcloud storage rm --recursive "gs://${CLOUDBUILD_BUCKET_NAME}"
   
   gcloud projects remove-iam-policy-binding $PROJECT_ID \
       --member="serviceAccount:$[e-mail]" \
       --role="roles/artifactregistry.writer"
   
   gcloud projects remove-iam-policy-binding $PROJECT_ID \
       --member="serviceAccount:$[e-mail]" \
       --role="roles/logging.logWriter"
   

A seguir

• Saiba como isolar a execução de código de IA: acionador externo.
• Saiba como salvar e restaurar ambientes do sandbox do agente.
• Para entender as camadas de isolamento que protegem suas cargas de trabalho não confiáveis, consulte GKE Sandbox.
• Confira o projeto de sandbox do agente de código aberto no GitHub.
• Saiba como usar o Kata Containers de código aberto com o sandbox do agente. O Kata Containers não é um Google Cloud produto. Se você instalar e usar esse software, será responsável pelo gerenciamento e pela solução de problemas. O suporte e os SLAs do Google não se aplicam ao Kata Containers.