Cette page a été traduite par l'API Cloud Translation.

Isoler l'exécution du code d'IA avec Agent Sandbox

Ce document fournit des instructions pour installer et exécuter le contrôleur Agent Sandbox sur un cluster Google Kubernetes Engine (GKE). Il explique également comment déployer un environnement en bac à sable sur le cluster dans lequel vous pouvez tester des commandes shell non approuvées.

Le contrôleur Agent Sandbox fournit un framework pour créer et gérer des environnements d'exécution éphémères. Cette approche vous permet de définir un modèle pour l'environnement de votre application, puis de créer des instances à la demande.

Le bac à sable de l'agent fournit un environnement sécurisé et isolé pour exécuter du code non fiable, 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 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.

L'Agent Sandbox atténue ces risques en fournissant une isolation forte des processus, du stockage et du réseau pour le code qu'il exécute. Cette isolation est obtenue à l'aide de gVisor, une technologie qui crée une barrière sécurisée entre l'application et le système d'exploitation du nœud de cluster. D'autres technologies de bac à sable, par exemple les conteneurs Kata, peuvent être utilisées à la place. Toutefois, l'exemple de ce document n'utilise que gVisor.

Ce document fournit des instructions pour exécuter Agent Sandbox sur un cluster GKE Autopilot ou Standard.

Agent Sandbox est un projet Open Source. Pour savoir comment contribuer au projet ou obtenir des informations techniques plus détaillées, consultez le projet Open Source Agent Sandbox.

Coûts

Les étapes décrites dans ce document entraînent des frais sur votre compte Google Cloud. Les coûts commencent lorsque vous créez un cluster GKE. Ces coûts incluent les frais par cluster pour GKE, comme indiqué sur la page de tarification, et les frais d'exécution des VM Compute Engine.

Pour éviter des frais inutiles, assurez-vous de désactiver GKE ou de supprimer le projet une fois que vous avez terminé ce document.

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 Artifact Registry, Google Kubernetes Engine 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

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. Dans Cloud Shell, définissez les variables d'environnement utiles suivantes en exécutant les commandes suivantes :
```
export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"
export PYTHON_CLIENT_VERSION="main"
```
Voici une explication de ces variables d'environnement :
- PROJECT_ID : ID de votre projet actuel Google Cloud . 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 et votre dépôt Artifact Registry seront créés (par exemple, us-central1). Nous vous recommandons de les colocaliser, car cela réduit la latence d'extraction des images.
- 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 e2-standard-2. 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.
- PYTHON_CLIENT_VERSION : version du client Python Agentic Sandbox à installer.
Déployer le bac à sable de l'agent

Maintenant que votre projet Google Cloud et votre environnement Cloud Shell sont configurés, vous êtes prêt à provisionner l'infrastructure nécessaire et à déployer Agent Sandbox.

Créer un cluster GKE

Vous allez maintenant créer un cluster GKE avec gVisor activé. Ce cluster fournit l'environnement Kubernetes dans lequel vous allez déployer et exécuter le contrôleur Agent Sandbox et l'exemple d'application en bac à sable. gVisor fournit la technologie de bac à sable pour exécuter du code non approuvé de manière sécurisée.

Vous pouvez créer un cluster Autopilot ou Standard. Autopilot active gVisor automatiquement, tandis que les clusters standards vous obligent à créer manuellement un pool de nœuds compatible avec gVisor :
Autopilot
Pour créer un cluster Autopilot à l'aide de la gcloud CLI, exécutez la commande suivante :
```
gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}
```
Standard
Pour créer un cluster standard à l'aide de la gcloud CLI, procédez comme suit :
1. Créez le cluster :
  gcloud container clusters create ${CLUSTER_NAME} \ --location=${GKE_LOCATION}
2. Créez un pool de nœuds distinct avec gVisor activé :
  gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --location=${GKE_LOCATION} \ --machine-type=${MACHINE_TYPE} \ --image-type=cos_containerd \ --sandbox type=gvisor
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}
```
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.

Exécutez les commandes suivantes pour déployer le contrôleur Agent Sandbox sur votre cluster GKE :
```
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 du bac à sable de l'agent

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 :
```
kubectl get pods -n agent-sandbox-system
```
Attendez que le pod affiche "Running" (En cours d'exécution) dans la colonne ÉTAT et "1/1" dans la colonne PRÊT. 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.

Déployer un environnement de bac à sable

Maintenant que le contrôleur Agent Sandbox s'exécute dans votre cluster GKE, vous devez déployer les composants de l'environnement de bac à sable exemple. Cette section vous explique comment créer le blueprint du bac à sable (SandboxTemplate), déployer le routeur réseau nécessaire et installer le client Python que vous utiliserez pour interagir avec le bac à sable.

La méthode recommandée pour créer votre bac à sable et interagir avec lui consiste à utiliser le client Python Agentic Sandbox. Ce client fournit une interface qui simplifie l'ensemble du cycle de vie d'un bac à sable, de la création au nettoyage. Il s'agit d'une bibliothèque Python que vous pouvez utiliser pour créer, utiliser et supprimer des bacs à sable de manière programmatique.

Le client utilise un routeur Sandbox comme point d'entrée central pour tout le trafic. Dans l'exemple décrit dans ce document, le client crée un tunnel vers ce routeur à l'aide de la commande kubectl port-forward, de sorte que vous n'avez pas besoin d'exposer d'adresses IP publiques. Sachez que l'utilisation de kubectl port-forward n'est pas une solution sécurisée et qu'elle doit être limitée aux environnements de développement.

Créer un SandboxTemplate et un SandboxWarmPool

Vous allez maintenant définir la configuration de votre bac à sable en créant une ressource SandboxTemplate et une ressource SandboxWarmPool. SandboxTemplate sert de plan réutilisable que le contrôleur Agent Sandbox utilise pour créer des environnements de bac à sable cohérents et préconfigurés. La ressource SandboxWarmPool garantit qu'un nombre spécifié de pods pré-chauffés sont toujours en cours d'exécution et prêts à être revendiqués. Un bac à sable préchauffé est un pod en cours d'exécution qui a déjà été initialisé. Cette pré-initialisation permet de créer de nouveaux bacs à sable en moins d'une seconde et évite la latence de démarrage d'un bac à sable normal :
1. Dans Cloud Shell, créez un fichier nommé sandbox-template-and-pool.yaml et contenant ce qui suit :
```
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      containers:
      - name: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
            ephemeral-storage: "512Mi"
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template
```
2. Appliquez les fichiers manifestes SandboxTemplate et SandboxWarmPool :
```
kubectl apply -f sandbox-template-and-pool.yaml
```
Déployer le routeur de bac à sable

Le client Python que vous utiliserez pour créer des environnements de bac à sable et interagir avec eux utilise un composant appelé Sandbox Router pour communiquer avec les bacs à sable.

Pour cet exemple, vous allez utiliser le mode développeur du client pour les tests. Ce mode est destiné au développement local et utilise la commande kubectl port-forward pour établir un tunnel direct entre votre machine locale et le service Sandbox Router exécuté dans le cluster. Cette approche de tunneling évite d'avoir besoin d'une adresse IP publique ou d'une configuration d'entrée complexe, et simplifie l'interaction avec les bacs à sable depuis votre environnement local.

Pour déployer le routeur Sandbox :
1. Dans Cloud Shell, créez un fichier nommé sandbox-router.yaml avec le contenu suivant :
```
# A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 2 # Run at least two replicas for high availability
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:v20251124-v0.1.0-10-ge26ddb2
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000
```
2. Appliquez le fichier manifeste pour déployer le routeur sur votre cluster :
```
kubectl apply -f sandbox-router.yaml
```
Installer le client Python

Maintenant que les composants du cluster, comme le routeur Sandbox, sont déployés, la dernière étape préparatoire consiste à installer le client Python Agentic Sandbox sur votre machine locale. Rappelons que ce client est une bibliothèque Python qui vous permet de créer, d'utiliser et de supprimer des bacs à sable de manière programmatique. Vous l'utiliserez dans la section suivante pour tester l'environnement :
1. Créez et activez un environnement virtuel Python :
```
python3 -m venv .venv
source .venv/bin/activate
```
2. Installez le package client à partir du dépôt agent-sandbox :
```
pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${PYTHON_CLIENT_VERSION}#subdirectory=clients/python/agentic-sandbox-client"
```
Tester le bac à sable

Maintenant que tous les composants de configuration sont en place, vous pouvez créer un bac à sable et interagir avec lui à l'aide du client Python Agentic Sandbox.
1. Dans votre répertoire agent-sandbox, créez un script Python nommé test_sandbox.py avec le contenu suivant :
```
from agentic_sandbox import SandboxClient

# Automatically tunnels to svc/sandbox-router-svc
with SandboxClient(
    template_name="python-runtime-template",
    namespace="default"
) as sandbox:
    print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
)
```
2. Depuis votre terminal (avec l'environnement virtuel toujours actif), exécutez le script de test :
```
python3 test_sandbox.py
```
Le message "Hello from the sandboxed environment!" (Bonjour depuis l'environnement de bac à sable !) doit s'afficher. Il s'agit de la sortie du bac à sable.

Félicitations ! Vous avez exécuté une commande shell dans un bac à sable sécurisé. La méthode sandbox.run() vous permet d'exécuter n'importe quelle commande shell. Le bac à sable de l'agent exécute la commande dans une barrière sécurisée qui protège les nœuds de votre cluster et les autres charges de travail contre le code non approuvé. Cela permet à un agent d'IA ou à tout workflow automatisé d'exécuter des tâches de manière sécurisée et fiable.

Lorsque vous exécutez le script, SandboxClient gère toutes les étapes pour vous. Il crée la ressource SandboxClaim pour démarrer le bac à sable, attend que le bac à sable soit prêt, puis utilise la méthode sandbox.run() pour exécuter les commandes du shell bash à l'intérieur du conteneur sécurisé. Le client capture et imprime ensuite le stdout de cette commande. La sandbox est automatiquement supprimée après l'exécution du programme.

Effectuer un nettoyage des ressources

Pour éviter que des frais ne soient facturés sur votre compte Google Cloud , supprimez le cluster GKE que vous avez créé :
```
gcloud container clusters delete $CLUSTER_NAME --location=$GKE_LOCATION --quiet
```
Étapes suivantes
- Pour en savoir plus sur le projet Open Source Agent Sandbox, consultez GitHub.
- Pour comprendre la technologie sous-jacente qui assure l'isolation de sécurité de vos charges de travail, consultez GKE Sandbox.
- Pour en savoir plus sur l'amélioration de la sécurité de vos clusters et de vos charges de travail, consultez la présentation de la sécurité dans GKE.

Isoler l'exécution du code d'IA avec Agent Sandbox Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Coûts

Avant de commencer

Définir des variables d'environnement

Déployer le bac à sable de l'agent

Créer un cluster GKE

Autopilot

Standard

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

Vérifier le contrôleur du bac à sable de l'agent

Déployer un environnement de bac à sable

Créer un SandboxTemplate et un SandboxWarmPool

Déployer le routeur de bac à sable

Installer le client Python

Tester le bac à sable

Effectuer un nettoyage des ressources

Étapes suivantes

Isoler l'exécution du code d'IA avec Agent Sandbox

Créer un `SandboxTemplate` et un `SandboxWarmPool`