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 de l'agent améliore votre sécurité en fournissant un environnement isolé pour l'exécution de code non approuvé, tel que le 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 le 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 longtemps à 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
PodSnapshotManualTriggerpour 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é.
Avant de commencer
-
Dans la console Google Cloud , sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud .
Rôles requis pour sélectionner ou créer un projet
- Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
-
Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (
roles/resourcemanager.projectCreator), qui contient l'autorisationresourcemanager.projects.create. Découvrez comment attribuer des rôles.
-
Vérifiez que la facturation est activée pour votre projet Google Cloud .
Activez les API Google Kubernetes Engine, Cloud Storage et Identity and Access Management (IAM).
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (
roles/serviceusage.serviceUsageAdmin), qui contient l'autorisationserviceusage.services.enable. Découvrez comment attribuer des rôles.-
Dans la console Google Cloud , activez Cloud Shell.
Conditions requises
Les snapshots de pods GKE nécessitent GKE version 1.35.3-gke.1234000 ou ultérieure. Les modes Autopilot et Standard sont tous les deux compatibles.
Étant donné que les snapshots de pods nécessitent GKE Sandbox, votre environnement est soumis à certaines limites. Par exemple, 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.
Pour obtenir la liste complète des restrictions, y compris des informations sur l'utilisation des types de machines basés sur GPU, 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 retaper 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 CLUSTER_VERSION="1.35.3-gke.1234000"
export AGENT_SANDBOX_VERSION="v0.4.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)")
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).CLUSTER_VERSION: version de votre cluster GKE, qui doit être la version 1.35.3-gke.1234000 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 certaines é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 Workload Identity Federation for 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 :
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 répondant aux exigences
Créez un cluster GKE avec les instantanés de pods activés. Pour une compatibilité complète des fonctionnalités, spécifiez un cluster version 1.35.3-gke.1234000 ou ultérieure :
Autopilot
Créez un cluster Autopilot avec les fonctionnalités requises :
gcloud container clusters create-auto ${CLUSTER_NAME} \
--cluster-version=${CLUSTER_VERSION} \
--enable-pod-snapshots \
--location=${GKE_LOCATION}
Standard
Créez un cluster Standard avec les fonctionnalités requises :
gcloud container clusters create ${CLUSTER_NAME} \
--cluster-version=${CLUSTER_VERSION} \
--enable-pod-snapshots \
--machine-type=${MACHINE_TYPE} \
--workload-pool=${PROJECT_ID}.svc.id.goog \
--workload-metadata=GKE_METADATA \
--num-nodes=1 \
--location=${GKE_LOCATION}
Créez un pool de nœuds avec GKE Sandbox activé. GKE Sandbox est une fonctionnalité de sécurité des conteneurs basée sur le projet Open Source gVisor. Elle fournit une couche d'isolation supplémentaire entre les applications en cours d'exécution et le système d'exploitation hôte :
gcloud container node-pools create ${NODE_POOL_NAME} \
--cluster ${CLUSTER_NAME} \
--num-nodes=1 \
--location=${GKE_LOCATION} \
--project=${PROJECT_ID} \
--machine-type=${MACHINE_TYPE} \
--sandbox type=gvisor
Récupérer les identifiants
Récupérez les identifiants du cluster afin que la CLI kubectl puisse s'y connecter :
gcloud container clusters get-credentials ${CLUSTER_NAME} \
--location=${GKE_LOCATION}
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
Valider 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 d'instantanés 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 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 des 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é
podSnapshotGcsReadWritercontenant 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: podSnapshotGcsReadWriterCré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
podSnapshotGcsReadWriterpersonnalisé au compte de service Kubernetes pour votre bac à sable. Cette liaison permet à ce compte spécifique uniquement 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.objectUserau compte de service Kubernetes. Ce rôle est nécessaire 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/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
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 yamlLe résultat doit contenir une condition avec
type: Readyetstatus: "True":status: conditions: - lastTransitionTime: "2025-10-31T18:18:02Z" message: Valid PodSnapshotStorageConfig reason: StorageConfigValid status: "True" type: ReadyVérifiez l'état de la ressource
PodSnapshotPolicy:kubectl get podsnapshotpolicies.podsnapshot.gke.io cpu-psp \ --namespace "${SNAPSHOT_NAMESPACE}" -o yamlLe résultat doit contenir une condition avec
type: Readyetstatus: "True". Il doit également indiquer que lePodSnapshotStorageConfigré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.
Autopilot
Les snapshots de pods ne sont pas compatibles avec les types de machines E2. Dans Autopilot, GKE peut utiliser les nœuds E2 par défaut. Pour vous assurer que vos charges de travail s'exécutent sur du matériel compatible, vous devez utiliser une ComputeClass personnalisée pour hiérarchiser les familles de machines compatibles.
Enregistrez le manifeste suivant sous le nom
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: DoNotScaleUpAppliquez le fichier manifeste :
kubectl apply -f non-e2-class.yamlPour créer les ressources
SandboxTemplateetSandboxClaim, appliquez le manifeste suivant. Notez queSandboxTemplatefait référence àComputeClassque vous venez de créer à l'aide du sélecteur de nœudscloud.google.com/compute-class: non-e2-class.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 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/v1alpha1 kind: SandboxClaim metadata: name: python-sandbox-example namespace: ${SNAPSHOT_NAMESPACE} labels: app: agent-sandbox-workload spec: sandboxTemplateRef: name: python-runtime-template EOF
Standard
Pour créer les ressources SandboxTemplate et SandboxClaim, appliquez le 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 de compteur initiaux : 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=5Le résultat affiche les dernières lignes du compteur, par exemple :
Count: 15 Count: 16 Count: 17Notez les dernières valeurs "Count" affichées.
Créez une ressource PodSnapshotManualTrigger : lancez l'instantané :
kubectl apply -f - <<EOF apiVersion: podsnapshot.gke.io/v1 kind: PodSnapshotManualTrigger metadata: name: cpu-snapshot-trigger namespace: ${SNAPSHOT_NAMESPACE} spec: targetPod: python-sandbox-example EOFVé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 XXsAffichez 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 Createdavec 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
SandboxClaimpour 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 EOFVé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, par exemple :
Count: 18 Count: 19 Count: 20 Count: 21
Effectuer un nettoyage des ressources
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-gcsSi vous en avez créé une pour Autopilot, supprimez la ComputeClass.
kubectl delete computeclass non-e2-classSupprimez 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}" --quietSupprimez 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.