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

Vous pouvez déployer un environnement de développement pour utiliser le client Python Agent Sandbox sur un cluster Google Kubernetes Engine (GKE). Cette configuration vous permet d'exécuter et de tester en toute sécurité le code généré par l'IA en isolant le code non approuvé dans un environnement Python en bac à sable. Cette isolation est essentielle pour protéger votre système contre les failles potentielles du code généré par l'IA, accélérer le développement et garantir des déploiements sécurisés. Pour obtenir une présentation de la façon dont la fonctionnalité Agent Sandbox isole le code non approuvé généré par l'IA, consultez À propos de GKE Agent Sandbox.

Coûts

Agent Sandbox est proposé sans frais supplémentaires dans GKE. Les tarifs de GKE s'appliquent aux ressources que vous créez.

Avant de commencer

  1. Dans la Cloud de Confiance console, sur la page de sélection du projet, sélectionnez ou créez un Cloud de Confiance projet.

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionner 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'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    Accéder au sélecteur de projet

  2. Vérifiez que la facturation est activée pour votre Cloud de Confiance projet.

  3. Activez les API Artifact Registry et Kubernetes Engine.

    Rôles requis pour activer les API

    Pour activer les API, vous devez disposer du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    Activer les API

  4. Dans la Cloud de Confiance console, activez Cloud Shell.

    Activer Cloud Shell

  5. Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce guide.
  6. Vous devez disposer d'un cluster GKE sur lequel la fonctionnalité Agent Sandbox est activée. Si vous n'en avez pas, suivez les instructions de la section Activer Agent Sandbox sur GKE pour créer un cluster ou en mettre à jour un existant.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des bacs à sable, demandez à votre administrateur de vous attribuer le rôle IAM Administrateur Kubernetes Engine (roles/container.admin) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

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 LOCATION="us-central1"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"

Voici une explication de ces variables d'environnement :

  • PROJECT_ID : ID de votre projet actuel. Cloud de Confiance by S3NS 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.
  • LOCATION : région ou zone où se trouve votre cluster GKE . Cloud de Confiance by S3NS Définissez cette valeur sur la région (par exemple, us-central1) si vous utilisez un cluster Autopilot, ou sur la zone (par exemple, us-central1-a) si vous utilisez un cluster Standard.
  • 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 différentes options, consultez le Guide des ressources de familles de machines et guide comparatif.

Déployer un environnement en bac à sable

Cette section explique comment créer le plan de 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 et interagir avec votre bac à sable 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 par programmation.

Le client utilise un routeur de bac à sable 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. Le SandboxTemplate fait office de plan réutilisable que le contrôleur Agent Sandbox utilise pour créer des environnements en bac à sable cohérents et préconfigurés. La ressource SandboxWarmPool permet de s'assurer 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 est déjà initialisé. Cette pré-initialisation permet de créer de nouveaux bacs à sable en moins d'une seconde et évite la latence de démarrage du lancement d'un bac à sable normal :

  1. Dans Cloud Shell, créez un fichier nommé sandbox-template-and-pool.yaml 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
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      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"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      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 le fichier manifeste 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 et interagir avec des environnements en bac à sable utilise un composant appelé routeur de bac à sable pour communiquer avec les bacs à sable.

Pour cet exemple, vous utilisez 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 de routeur de bac à sable 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 de bac à sable, procédez comme suit :

  1. Dans Cloud Shell, créez un fichier nommé sandbox-router.yaml contenant ce qui suit :

    # 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: 1
  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:latest-main
        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: "100m"
            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

  3. Vérifiez que le déploiement du routeur de bac à sable s'exécute correctement :

    kubectl get deployment sandbox-router-deployment

    Attendez que le déploiement affiche 2/2 ou 1/1 dans la colonne READY.

Installer le client Python

Maintenant que les composants du cluster, tels que le routeur de bac à sable, 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 par programmation. 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 :

    pip install k8s-agent-sandbox

Tester le bac à sable

Une fois tous les composants de configuration 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 contenant ce qui suit :

    from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

# Automatically tunnels to svc/sandbox-router-svc
client = SandboxClient(
    connection_config=SandboxLocalTunnelConnectionConfig()
)

sandbox = client.create_sandbox(template="python-runtime-template", namespace="default")
try:
    print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  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 en bac à sable !) doit s'afficher.

Félicitations ! Vous avez exécuté une commande shell dans un bac à sable sécurisé. À l'aide de la méthode sandbox.run(), vous pouvez exécuter n'importe quelle commande shell, et Agent Sandbox 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 fournit un moyen sûr et fiable pour un agent IA ou tout workflow automatisé d'exécuter des tâches.

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 qu'il soit prêt, puis utilise la méthode sandbox.run() pour exécuter des commandes shell bash dans le conteneur sécurisé. Le client capture et affiche ensuite le stdout de cette commande. Le bac à sable est automatiquement supprimé après l'exécution du programme.

Lorsqu'une ressource SandboxClaim est créée, un pod disponible est attribué du pool chaud à l'objet Sandbox et la revendication est marquée comme prête. Le SandboxWarmPool se remplit ensuite automatiquement pour maintenir le nombre de répliques configuré.

Pour vérifier si un bac à sable spécifique est revendiqué ou disponible, vérifiez les ownerReferences dans les métadonnées du pod de bac à sable. Si la valeur du champ kind est Sandbox, le pod est en cours d'utilisation. Si la valeur du champ kind est SandboxWarmPool, le pod est inactif et en attente d'être revendiqué.

Exécuter des bacs à sable en production

Dans ce document, vous interagissez avec des bacs à sable en dehors du cluster à l'aide de Cloud Shell. Le client Python utilise vos identifiants utilisateur pour s'authentifier auprès du cluster et gérer les ressources de bac à sable, et utilise la commande kubectl port-forward pour établir une connexion avec les bacs à sable. Ces étapes fonctionnent bien pour les scénarios de développement.

Dans un scénario de production, une application de contrôleur (telle qu'un orchestrateur d'IA) est chargée de créer et de gérer les ressources de bac à sable. Pour utiliser Agent Sandbox en production, tenez compte des points suivants :

  • Authentification : votre application de contrôleur doit s'authentifier auprès du serveur d'API du cluster pour exécuter des bacs à sable. La façon dont vous configurez l'authentification dépend de l'endroit où l'application de contrôleur s'exécute, comme suit :

    • Si l'application de contrôleur s'exécute en tant que pod dans le même cluster, utilisez Kubernetes RBAC ou Workload Identity Federation for GKE avec des stratégies IAM pour accorder au compte de service Kubernetes du pod les autorisations nécessaires pour surveiller les bacs à sable ou découvrir les points de terminaison réseau.
    • Si l'application de contrôleur s'exécute en dehors du cluster, utilisez Workload Identity Federation, ou des comptes de service IAM pour attribuer à l'application une identité que vous pouvez référencer dans les stratégies d'autorisation.

  • Routage : les requêtes du client Python dans votre application de contrôleur doivent atteindre le routeur de bac à sable de votre cluster. En production, utilisez l'une des méthodes suivantes pour établir une connexion réseau :

    • Si l'application de contrôleur s'exécute dans le même cluster, utilisez la fonction SandboxDirectConnectionConfig pour cibler l'URL et le port utilisés par le service de routeur de bac à sable.
    • Si l'application de contrôleur s'exécute en dehors du cluster, utilisez l' API GKE Gateway pour créer un équilibreur de charge interne ou externe. Dans le code de votre client, utilisez la fonction SandboxGatewayConnectionConfig pour référencer votre passerelle.

    Pour en savoir plus sur ces méthodes de routage, consultez les exemples d'utilisation sur GitHub et les étapes de déploiement de la passerelle pour le routeur.

  • Accès du bac à sable aux Cloud de Confiance ressources : si le code de votre bac à sable doit envoyer des requêtes à des Cloud de Confiance API, telles que Cloud Storage, utilisez une stratégie IAM avec Workload Identity Federation for GKE pour accorder au compte de service Kubernetes utilisé par le pod de bac à sable les autorisations requises pour cet accès. Étant donné que la règle de réseau par défaut bloque l'accès au Cloud de Confiance by S3NS serveur de métadonnées (169.254.169.254), vous devez personnaliser la règle de réseau pour autoriser ce trafic.

  • Restrictions de la règle de réseau : par défaut, Agent Sandbox applique une posture réseau stricte sécurisée par défaut (networkPolicyManagement: Managed). Les restrictions suivantes s'appliquent dans cette posture :

    • L'entrée est bloquée à partir de toutes les sources, à l'exception du routeur de bac à sable désigné.
    • La sortie est autorisée sur l'Internet public, mais la sortie vers les plages de LAN privé (RFC 1918), le DNS de cluster interne (CoreDNS) et le serveur de métadonnées du fournisseur cloud (169.254.0.0/16) est explicitement bloquée.

    Pour utiliser Workload Identity Federation for GKE ou accéder à d'autres ressources privées, vous devez définir des règles de réseau personnalisées dans le SandboxTemplate. Pour obtenir des informations détaillées sur la configuration et des modèles personnalisables (tels que les bacs à sable isolés ou l'intégration de Workload Identity Federation for GKE), consultez Gestion des règles de réseau Agent Sandbox.

Règles de sécurité du bac à sable

Pour garantir un environnement sécurisé par défaut, l'addon GKE Agent Sandbox utilise des règles d'admission de validation Kubernetes (VAP) pour appliquer des contraintes de sécurité aux ressources Sandbox et SandboxTemplate. Ces règles sont appliquées automatiquement.

L'addon divise l'application de la sécurité en un modèle de règles à deux niveaux pour une plus grande flexibilité. Les sections suivantes décrivent ces règles : la règle de base strictement gérée et la règle de renforcement personnalisable.

Règle de sécurité de base (sandbox-core-policy)

La règle de sécurité de base applique des exigences d'isolation qui contribuent à protéger l'intégrité du bac à sable. Cette règle inclut des règles qui nécessitent l'utilisation de gVisor, l'isolation réseau telle que la désactivation de hostNetwork et l'isolation du système de fichiers telle que le blocage de hostPath. Étant donné que GKE gère cette règle via le paramètre addonmanager.kubernetes.io/mode: Reconcile, vous ne pouvez pas modifier ni remplacer ces règles de base.

Règle de sécurité de renforcement (sandbox-hardening-policy)

La règle de sécurité de renforcement fournit des bonnes pratiques de sécurité et des options de gestion supplémentaires. Elle applique des contraintes telles que la suppression de toutes les fonctionnalités, l'empêchement de l'ajout de nouvelles fonctionnalités et l'exigence que les conteneurs s'exécutent en tant qu'utilisateur non racine avec des limites de ressources. GKE déploie cette règle en mode EnsureExists via le paramètre addonmanager.kubernetes.io/mode: EnsureExists. Ce paramètre signifie que GKE crée la règle si elle est manquante, mais vous pouvez modifier ou supprimer la règle ou sa liaison si nécessaire.

Modifier ou supprimer des contraintes de renforcement

Étant donné que la règle de renforcement est déployée en mode EnsureExists, GKE crée la règle si elle est manquante, mais n'écrase pas vos modifications. Si vos charges de travail nécessitent des exemptions à ces règles de renforcement, vous pouvez modifier la règle pour supprimer des contraintes spécifiques ou supprimer complètement la liaison de la règle.

Pour modifier la règle de renforcement et supprimer une contrainte spécifique (par exemple, pour autoriser l'exécution des conteneurs en tant qu'utilisateur racine ou omettre les limites de ressources), modifiez la ressource ValidatingAdmissionPolicy :

kubectl edit validatingadmissionpolicy sandbox-hardening-policy

Dans l'éditeur de texte qui s'ouvre, recherchez la section validations, puis supprimez ou modifiez l'expression de contrainte qui bloque votre charge de travail.

Vous pouvez également désactiver complètement la règle de renforcement pour votre cluster en supprimant la liaison de la règle :

kubectl delete validatingadmissionpolicybinding sandbox-hardening-binding

Problèmes connus

Cette section décrit les problèmes connus lors de l'utilisation d'Agent Sandbox dans GKE, ainsi que la manière de les résoudre ou de les contourner.

La règle de sécurité bloque les fonctionnalités lors de l'utilisation d'un maillage de services

Si vous tentez de déployer un bac à sable qui s'intègre à un side-car de maillage de services (par exemple, Envoy ou Istio), la création du bac à sable peut être bloquée par la règle de sécurité de renforcement avec une erreur semblable à la suivante :

sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'sandbox-hardening-policy' with binding 'sandbox-hardening-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.
  • Cause : les side-cars de maillage de services utilisent souvent un conteneur d'initialisation, tel que istio-init ou proxy-init. Ces conteneurs d'initialisation nécessitent des fonctionnalités telles que NET_ADMIN ou NET_RAW pour configurer les règles iptables pour le routage de sortie transparent. Par défaut, la règle sandbox-hardening-policy de GKE bloque tous les ajouts de fonctionnalités dans tous les types de conteneurs.
  • Solution : étant donné que la règle de renforcement de GKE est déployée en mode EnsureExists, vous pouvez modifier le ValidatingAdmissionPolicy pour autoriser des conteneurs d'initialisation approuvés spécifiques à demander les fonctionnalités NET_ADMIN et NET_RAW. Pour savoir comment modifier ou supprimer ces contraintes de renforcement, consultez Modifier ou supprimer des contraintes de renforcement. Par exemple, vous pouvez mettre à jour les expressions ou les variables de validation de la règle pour exempter les noms de conteneurs approuvés de la règle de fonctionnalités.

Latence de sortie ou délai d'expiration lors de la connexion aux API Google via IPv6

Les charges de travail à l'intérieur du bac à sable peuvent rencontrer des délais d'expiration de connexion ou une latence élevée (jusqu'à deux minutes) lorsqu'elles tentent de se connecter à des ressources externes ou à des API Google (telles que Vertex AI ou Cloud Storage).

  • Cause : si votre cluster GKE est compatible avec la double pile IPv6, la résolution DNS pour les API Google renvoie des adresses IPv4 (A) et IPv6 (AAAA) adresses. Certains algorithmes des moteurs d'exécution, tels que Node.js, tentent d'abord de se connecter via IPv6. Si votre VPC GKE ne dispose pas d'une route de sortie IPv6 valide, telle qu'une passerelle Cloud NAT ou Internet pour IPv6, la connexion TCP cesse de répondre (pour en savoir plus, consultez https://developers.google.com/style/word-list#hang) jusqu'à l'expiration du délai d'expiration TCP SYN. La connexion TCP revient ensuite à IPv4.

  • Résolution : pour résoudre ce problème, effectuez l'une des opérations suivantes :

    • Configurer la sortie IPv6 : pour autoriser le trafic IPv6 sortant à revenir au cluster, configurez une passerelle Cloud NAT ou Internet IPv6 valide dans votre réseau VPC.

    • Préférer IPv4 dans la charge de travail : pour préférer la résolution DNS IPv4, configurez l'exécution de votre charge de travail. Par exemple, dans une application Node.js, vous pouvez définir les variables d'environnement suivantes dans votre définition SandboxTemplate :

      env:
- name: NODE_OPTIONS
  value: "--dns-result-order=ipv4first --no-network-family-autoselection"

Effectuer un nettoyage des ressources

Pour éviter que des frais ne soient facturés sur votre Cloud de Confiance by S3NS compte, supprimez le cluster GKE que vous avez créé :

gcloud container clusters delete $CLUSTER_NAME --location=$LOCATION --quiet

Étape suivante