Enregistrer et restaurer des environnements de bac à sable Agent avec des instantanés de pod

Standard

Ce document ne concerne que les clusters Standard.

Ce document vous explique comment utiliser les instantanés de pods GKE pour enregistrer l'état d'un environnement Agent Sandbox en cours d'exécution.

Le bac à sable d'agent fournit un environnement sécurisé et isolé pour exécuter du code non fiable, tel que du code généré par de grands modèles de langage (LLM). L'exécution de ce type de code directement dans un cluster présente des risques de sécurité, car du code non approuvé peut potentiellement accéder à d'autres applications ou au nœud de cluster sous-jacent lui-même, ou interférer avec eux.

Les instantanés de pods GKE vous permettent d'enregistrer et de restaurer l'état des environnements en bac à sable. Cette fonctionnalité est utile pour les raisons suivantes :

Démarrage rapide : réduisez le temps de démarrage du bac à sable en restaurant un instantané préchauffé.
Agents de longue durée : mettez en pause un bac à sable qui met du temps à s'exécuter et reprenez-le plus tard, ou déplacez-le vers un autre nœud, sans perdre votre progression.
Les charges de travail avec état conservent le contexte d'un agent, comme l'historique des conversations ou les calculs intermédiaires, en enregistrant et en restaurant l'état de son environnement sandboxé.
Reproductibilité : capturez un état spécifique et utilisez-le comme base pour démarrer plusieurs bacs à sable avec le même état initialisé.

Il existe deux façons de déclencher un instantané :

Déclencheur manuel : vous créez une ressource PodSnapshotManualTrigger pour déclencher l'instantané.
Déclencheur de charge de travail : l'application sandboxée elle-même signale quand elle est prête à être enregistrée.

Ce document vous explique comment déclencher manuellement un instantané.

Remarque : Les instantanés de pods GKE sont une fonctionnalité en preview.

Avant de commencer

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

Conditions requises

Pour utiliser les instantanés de pods GKE, vous avez besoin d'un cluster en mode Standard exécutant GKE version 1.34.1-gke.3084001 ou ultérieure. Nous vous recommandons d'utiliser GKE version 1.35 ou ultérieure. La version 1.34 de GKE présente un problème connu : la création de points de contrôle peut échouer en raison d'une erreur d'entrée/sortie liée à des bugs d'autorisation Cloud Storage.

Les snapshots de pods ne sont pas compatibles avec les types de machines E2. Par conséquent, ce tutoriel crée un pool de nœuds composé de machines N2.

Si vous souhaitez utiliser des types de machines basés sur des GPU pour les nœuds de votre pool de nœuds, consultez Limites et exigences.

Définir des variables d'environnement

Pour simplifier les commandes que vous exécutez dans ce document, vous pouvez définir des variables d'environnement dans Cloud Shell. Ces variables stockent des valeurs telles que l'ID de votre projet Google Cloud , le nom du bucket Cloud Storage qui stockera vos instantanés et l'emplacement de votre cluster GKE.

Une fois ces variables définies, vous pouvez les réutiliser dans plusieurs commandes en faisant référence au nom de la variable (par exemple, $CLUSTER_NAME) au lieu de saisir ou de remplacer les valeurs à chaque fois. Cette approche facilite le processus et réduit le risque d'erreurs.

Pour définir les variables d'environnement utiles suivantes dans Cloud Shell, exécutez les commandes suivantes :

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

Voici une explication de ces variables d'environnement :

PROJECT_ID : ID de votre projet Google Cloud actuel. La définition de cette variable permet de s'assurer que toutes les ressources, comme votre cluster GKE, sont créées dans le bon projet.
CLUSTER_NAME : nom de votre cluster GKE (par exemple, agent-sandbox-cluster).
GKE_LOCATION : région Google Cloud dans laquelle votre cluster GKE sera créé (par exemple, us-central1).
GKE_VERSION : version du cluster et des nœuds GKE requise pour la compatibilité avec les instantanés de pods. Les snapshots de pods GKE nécessitent GKE version 1.34.1-gke.3084001 ou ultérieure.
AGENT_SANDBOX_VERSION : version du contrôleur Agent Sandbox à déployer sur votre cluster.
NODE_POOL_NAME : nom du pool de nœuds qui exécutera les charges de travail en bac à sable (par exemple, agent-sandbox-node-pool).
MACHINE_TYPE : type de machine des nœuds de votre pool de nœuds (par exemple, n2-standard-2). Les snapshots de pods ne sont pas compatibles avec les types de machines E2. Si vous souhaitez utiliser des types de machines basés sur des GPU pour les nœuds de votre pool de nœuds, consultez Limites et exigences. Pour en savoir plus sur les différentes séries de machines et sur le choix entre les différentes options, consultez le Guide des ressources de familles de machines et guide comparatif.
SNAPSHOTS_BUCKET_NAME : nom du bucket Cloud Storage que vous allez créer pour stocker les instantanés.
SNAPSHOT_NAMESPACE : espace de noms Kubernetes dans lequel résideront votre charge de travail et votre compte de service de snapshot.
SNAPSHOT_KSA_NAME : nom du compte de service Kubernetes que votre charge de travail utilisera pour s'authentifier.
SNAPSHOT_FOLDER : répertoire de votre bucket Cloud Storage dans lequel les instantanés seront organisés.
PROJECT_NUMBER : identifiant numérique unique de votre projet, utilisé pour les liaisons d'autorisations IAM.

Présentation des étapes de configuration

Pour activer les instantanés de pods des environnements Agent Sandbox, vous devez effectuer quelques étapes de configuration. Pour comprendre ces étapes, il est utile de commencer par comprendre quelques concepts clés, puis le processus d'instantané :

Concepts clés

Environnement : une application en bac à sable s'exécute dans un pod Kubernetes sur un nœud de cluster GKE.
Identité : le pod est associé à un compte de service Kubernetes et s'exécute dans un espace de noms spécial que vous créez. Ensemble, le compte de service Kubernetes et l'espace de noms forment une identité unique qui est utilisée pour accorder au pod un accès sécurisé aux ressources Google Cloud .
Autorisations : pour que les instantanés puissent être enregistrés dans Cloud Storage, l'identité du pod doit disposer d'autorisations IAM spécifiques lui permettant d'écrire dans un bucket Cloud Storage.

Processus d'instantané

Déclencheur : un instantané est lancé manuellement (en externe) ou par la charge de travail en bac à sable elle-même. Ce document présente un déclencheur manuel que vous lancez en créant une ressource PodSnapshotManualTrigger.
Capture : GKE capture l'état d'exécution du pod, tel que l'état de la mémoire et du système de fichiers du pod.
Importation : à l'aide des autorisations accordées au compte de service Kubernetes du pod, GKE importe l'état capturé sous forme de fichiers instantanés dans le bucket Cloud Storage désigné.

Pour en savoir plus sur la façon dont GKE utilise les comptes de service Kubernetes et les rôles IAM pour accéder aux ressources Google Cloud , consultez S'authentifier auprès des API Google Cloud à partir de charges de travail GKE.

Pour activer les instantanés de pods des environnements Agent Sandbox, effectuez la configuration suivante. Tout d'abord, préparez un environnement de cluster en créant un cluster GKE avec la fédération d'identité de charge de travail pour GKE et les fonctionnalités de snapshots de pods activées. Ensuite, vous configurez Cloud Storage et les règles IAM pour vous assurer que vos instantanés sont stockés de manière sécurisée et que votre bac à sable dispose des autorisations nécessaires. Enfin, vous créez les ressources d'instantané qui spécifient l'emplacement de stockage et les règles pour votre bac à sable.

Le tableau suivant récapitule les étapes de configuration que vous devez effectuer. Chaque étape est expliquée dans les sections suivantes :

Sujet	Tâche
Configurer un cluster	1. Créez un cluster GKE et activez les fonctionnalités de fédération d'identité de charge de travail pour GKE et d'instantanés de pods. 2. Déployez le bac à sable de l'agent.
Configurer le stockage et les autorisations	1. Créez le bucket Cloud Storage et le dossier géré. 2. Créez le rôle IAM personnalisé. 3. Créez l'espace de noms Kubernetes et le compte de service Kubernetes (KSA). 4. Associez le rôle IAM au compte de service Kubernetes. 5. Accordez des autorisations au contrôleur de snapshots.
Configurer les ressources d'instantané	1. Créer `PodSnapshotStorageConfig` 2. Créer `PodSnapshotPolicy` 3. Créer `SandboxTemplate`

Configurer le cluster

Une application en bac à sable s'exécute dans un pod sur un nœud de cluster GKE. Vous devez donc configurer un environnement de cluster. Cette section vous explique comment créer un cluster GKE et déployer le contrôleur Agent Sandbox.

Créer un cluster GKE

Créez un cluster GKE Standard. Ce cluster fournit l'environnement Kubernetes dans lequel vous allez créer un instantané d'un environnement bac à sable de l'agent. La commande suivante crée le cluster et active la fédération d'identité de charge de travail pour GKE et la fonctionnalité d'instantanés de pods :

Pour créer un cluster Standard à l'aide de la Google Cloud CLI, exécutez la commande suivante :

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

En plus de créer le cluster, cette commande active la fédération d'identité de charge de travail pour GKE et la fonctionnalité d'instantanés de pods sur le cluster.

Récupérez les identifiants du cluster afin que la CLI kubectl puisse s'y connecter. Cette commande met à jour votre fichier de configuration Kubernetes, qui est stocké par défaut dans le répertoire ~/.kube/config. Ce fichier de configuration contient les identifiants dont kubectl a besoin pour interagir avec votre cluster GKE :
```
gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}
```
Créez un pool de nœuds avec gVisor activé :
```
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
```
Cette commande utilise les options clés suivantes :
- --image-type=cos_containerd : indique que les nœuds utilisent Container-Optimized OS avec containerd.
- --sandbox type=gvisor : active la technologie de bac à sable gVisor sur les nœuds, ce qui est nécessaire pour Agent Sandbox.

Déployer le contrôleur Agent Sandbox sur votre cluster

Vous pouvez déployer le contrôleur Agent Sandbox et ses composants requis en appliquant les fichiers manifestes de la version officielle à votre cluster. Ces fichiers manifestes sont des fichiers de configuration qui indiquent à Kubernetes de télécharger tous les composants nécessaires au déploiement et à l'exécution du contrôleur Agent Sandbox sur votre cluster.

Pour déployer Agent Sandbox sur votre cluster GKE, exécutez la commande suivante :

# 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

Vérifier le contrôleur

Après avoir appliqué les manifestes, vérifiez que le pod du contrôleur Agent Sandbox s'exécute correctement dans l'espace de noms agent-sandbox-system. Les fichiers manifestes ont créé automatiquement l'espace de noms agent-sandbox-system lorsque vous les avez appliqués à l'étape précédente.

kubectl get pods -n agent-sandbox-system

Attendez que le pod affiche "Running" (En cours d'exécution) dans la colonne STATUS et "1/1" dans la colonne READY. Lorsque le pod s'exécute correctement, le résultat ressemble à ceci :

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

Maintenant que le contrôleur Agent Sandbox est en cours d'exécution, il peut créer et gérer automatiquement des environnements sandbox pour toutes les ressources Sandbox que vous créez dans votre cluster.

Configurer le stockage et les autorisations

Cette section vous explique comment configurer le stockage et les autorisations requis pour les instantanés de pods. Vous créez un bucket Cloud Storage et un dossier géré pour stocker les données de l'instantané. Ensuite, vous accordez à votre bac à sable et au contrôleur de snapshots les autorisations dont ils ont besoin pour accéder à ce stockage.

Créer le bucket Cloud Storage

Créez un bucket pour stocker vos instantanés. Pour que le processus de création d'instantanés soit rapide et économique, nous vous recommandons de créer le bucket avec les paramètres suivants :

Activer les espaces de noms hiérarchiques : la fonctionnalité d'espaces de noms hiérarchiques organise votre bucket dans une hiérarchie de système de fichiers plutôt que dans un espace de noms plat. Cette configuration permet d'obtenir un débit de lecture et d'écriture plus élevé, ce qui accélère l'enregistrement et la restauration des instantanés.
Désactiver la suppression réversible : la fonctionnalité de suppression réversible protège les données en conservant les fichiers supprimés pendant une période définie. Toutefois, le processus d'instantané crée et supprime de nombreux fichiers temporaires lors de l'importation. Nous vous recommandons de désactiver la suppression réversible pour éviter des frais inutiles liés au stockage de ces fichiers temporaires.

Pour créer le bucket avec ces paramètres, exécutez la commande suivante :

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

Créer un dossier géré

Créez un dossier géré pour organiser les instantanés dans votre bucket. Les dossiers gérés vous permettent d'appliquer des autorisations IAM à un dossier spécifique plutôt qu'à l'ensemble du bucket. Cet accès au niveau du dossier limite l'accès de votre bac à sable à ses propres instantanés uniquement et isole ces instantanés des autres données du bucket.

Pour créer un dossier géré, exécutez la commande suivante :

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

Configurer le compte de service et les rôles IAM

Pour permettre à GKE d'enregistrer les instantanés de manière sécurisée, le compte de service Kubernetes utilisé par les pods exécutant votre charge de travail en bac à sable doit être autorisé à écrire dans votre bucket. Pour accorder cette autorisation, vous devez associer des rôles IAM Google Cloudau compte de service Kubernetes utilisé par les pods. Cette section explique comment créer un rôle IAM personnalisé, créer le compte de service Kubernetes et configurer les autorisations nécessaires.

Créez un rôle IAM personnalisé appelé podSnapshotGcsReadWriter contenant les autorisations requises pour écrire des données d'instantané :

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

Une fois le rôle créé, le résultat est le suivant :

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

Créez l'espace de noms dans lequel résideront votre bac à sable et son compte de service :
```
kubectl create namespace "${SNAPSHOT_NAMESPACE}"
```
Créez le compte de service Kubernetes dans l'espace de noms que vous venez de créer. Le compte de service Kubernetes et l'espace de noms forment ensemble une identité unique utilisée pour accorder à votre bac à sable un accès sécurisé aux ressources Google Cloud :
```
kubectl create serviceaccount "${SNAPSHOT_KSA_NAME}" \
    --namespace "${SNAPSHOT_NAMESPACE}"
```

Attribuez le rôle roles/storage.bucketViewer à tous les comptes de service de l'espace de noms. Ce rôle permet aux comptes d'afficher les métadonnées du bucket, mais pas de lire ni d'écrire les données elles-mêmes :

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"

Attribuez votre rôle podSnapshotGcsReadWriter personnalisé au compte de service Kubernetes pour votre bac à sable. Cette liaison permet uniquement à ce compte spécifique d'écrire des données dans le dossier géré :

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"

Attribuez le rôle roles/storage.objectUser au compte de service Kubernetes. Ce rôle est requis pour que l'agent d'instantané du pod puisse effectuer des opérations sur les dossiers gérés :

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"

Accorder des autorisations au contrôleur d'instantanés

Accordez le rôle objectUser au contrôleur de snapshots du système GKE. Cette autorisation permet au contrôleur de gérer le cycle de vie des instantanés, par exemple en supprimant les objets d'instantané lorsque vous supprimez une ressource 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"

Configurer les ressources d'instantané

Cette section explique comment configurer les ressources de snapshot pour votre charge de travail Agent Sandbox.

Définir le stockage et les règles des instantanés

Pour spécifier où GKE enregistre vos instantanés et les règles qui régissent le processus d'instantané, vous devez créer deux ressources personnalisées :

PodSnapshotStorageConfig : cette ressource spécifie le bucket Cloud Storage et l'emplacement du dossier où GKE enregistre vos fichiers d'instantanés.
PodSnapshotPolicy : cette ressource définit les pods éligibles aux snapshots en fonction de leurs libellés Kubernetes. Il spécifie également les règles de déclenchement, par exemple si les instantanés sont manuels ou initiés par la charge de travail du bac à sable.

Pour appliquer les deux ressources en une seule étape, exécutez la commande suivante dans Cloud Shell. Cette méthode permet de s'assurer que vos variables d'environnement sont correctement injectées :

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

Vérifier la configuration

Après avoir appliqué la configuration et la règle de stockage des instantanés, vérifiez que les ressources sont prêtes à être utilisées. Cette section vous explique comment vérifier l'état de ces ressources personnalisées.

Vérifiez l'état de la ressource PodSnapshotStorageConfig :

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

Le résultat doit contenir une condition avec type: Ready et status: "True" :

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

Vérifiez l'état de la ressource PodSnapshotPolicy :

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

Le résultat doit contenir une condition avec type: Ready et status: "True". Il doit également indiquer que le PodSnapshotStorageConfig référencé a été trouvé :

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

Créer le modèle de bac à sable

Maintenant que les règles et les autorisations de stockage sont en place, vous pouvez créer les ressources SandboxTemplate et SandboxClaim. Pour que le processus de snapshot fonctionne, le bac à sable doit s'exécuter avec le compte de service Kubernetes que vous avez créé précédemment dans ce document. Le bac à sable doit également comporter les libellés que vous avez spécifiés précédemment dans PodSnapshotPolicy.

Cet exemple utilise une application Python qui affiche un compteur incrémentiel dans les journaux. Ce compteur vous permet de vérifier que l'état est bien enregistré et restauré ultérieurement.

Pour créer les ressources SandboxTemplate et SandboxClaim, appliquez le fichier manifeste suivant :

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

Votre bac à sable s'exécute désormais avec la bonne identité et est prêt à être instantané.

Créer un instantané

Cette section vous explique comment déclencher manuellement un instantané de votre bac à sable en cours d'exécution. Vous créez une ressource de déclencheur qui cible votre pod sandbox, puis vous vérifiez que le processus d'instantané se termine correctement.

Vérifiez les journaux du compteur initial : avant de déclencher l'instantané, consultez les journaux du bac à sable en cours d'exécution pour voir la valeur actuelle du compteur. L'affichage des journaux établit une référence à comparer après la restauration.
```
kubectl logs python-sandbox-example --namespace "${SNAPSHOT_NAMESPACE}" --tail=5
```
Le résultat affiche les dernières lignes du compteur, par exemple :
```
Count: 15
Count: 16
Count: 17
```
Notez les dernières valeurs "Count" affichées.

Créez une ressource PodSnapshotManualTrigger : lancez l'instantané :

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

Vérifiez que le déclencheur manuel a fonctionné :

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

Le résultat doit afficher l'état Complete, indiquant que GKE a bien déclenché l'instantané du pod cible :

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

Affichez plus de détails sur l'état capturé en décrivant le déclencheur :

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

La sortie contient une section Snapshot Created avec le nom unique des fichiers d'instantané stockés dans votre 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>

Effectuer une restauration à partir d'un instantané

Une fois l'instantané capturé, vous pouvez restaurer l'environnement de bac à sable pour reprendre l'exécution à partir de son état enregistré. Pour restaurer le bac à sable, créez un SandboxClaim qui fait référence au SandboxTemplate d'origine. Le contrôleur d'instantanés de pods identifie et restaure automatiquement l'instantané correspondant le plus récent.

Créez un SandboxClaim pour restaurer le bac à sable :

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

Vérifiez que la restauration a eu lieu en consultant les journaux. Notez que le compteur continue à partir du point où l'instantané a été pris :
```
kubectl logs python-sandbox-from-snapshot --namespace "${SNAPSHOT_NAMESPACE}"
```
Le résultat doit indiquer que le compteur reprend. Exemple :
```
Count: 18
Count: 19
Count: 20
Count: 21
```

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce document ne soient facturées sur votre compte Google Cloud , procédez comme suit pour supprimer les ressources que vous avez créées :

Supprimez les revendications du bac à sable pour arrêter les pods en cours d'exécution et permettre au contrôleur du bac à sable de l'agent d'arrêter progressivement les conteneurs.
```
kubectl delete sandboxclaims --all --namespace "${SNAPSHOT_NAMESPACE}"
```

Supprimez les modèles de bac à sable et les déclencheurs manuels utilisés pour créer des bacs à sable et lancer des instantanés.

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

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

Supprimez les règles d'instantané qui définissent les pods éligibles aux instantanés dans votre espace de noms.
```
kubectl delete podsnapshotpolicy cpu-psp --namespace "${SNAPSHOT_NAMESPACE}"
```
Supprimez la configuration du stockage des instantanés, qui correspond à la définition globale de votre backend de stockage des instantanés. Comme cette ressource est limitée au cluster, n'utilisez pas d'indicateur d'espace de noms.
```
kubectl delete podsnapshotstorageconfig cpu-pssc-gcs
```
Supprimez l'espace de noms Kubernetes pour supprimer automatiquement le compte de service Kubernetes et toutes les métadonnées restantes dans l'espace de noms.
```
kubectl delete namespace "${SNAPSHOT_NAMESPACE}"
```
Supprimez le cluster GKE pour supprimer l'infrastructure sous-jacente et tous les nœuds associés au tutoriel.
```
gcloud container clusters delete "${CLUSTER_NAME}" --location="${GKE_LOCATION}" --quiet
```
Supprimez le bucket Cloud Storage (facultatif) à l'aide de la commande de suppression récursive si vous souhaitez réinitialiser complètement votre stockage. Notez que vous pouvez ignorer cette étape si vous prévoyez de réutiliser votre bucket correctement configuré pour de futurs tests.
```
gcloud storage rm --recursive "gs://${SNAPSHOTS_BUCKET_NAME:?Error: SNAPSHOTS_BUCKET_NAME is not set. Please re-define the environment variables you defined earlier.}"
```
Supprimez le rôle IAM personnalisé (facultatif) si vous souhaitez que votre projet soit complètement propre. Étant donné que les rôles IAM persistent même après la suppression du cluster, vous devez les supprimer séparément.
```
gcloud iam roles delete podSnapshotGcsReadWriter --project="${PROJECT_ID}"
```

Étapes suivantes

En savoir plus sur les instantanés de pods GKE
Pour en savoir plus sur le projet Open Source Agent Sandbox, consultez GitHub.
Découvrez comment isoler l'exécution du code d'IA avec Agent Sandbox.