Isoler l'exécution de code d'IA avec Agent Sandbox sur GKE

Ce document explique comment exécuter du code généré par l'IA dans un bac à sable isolé sur un cluster Google Kubernetes Engine (GKE). Vous créez un modèle de bac à sable et un pool de bacs à sable prêts sur le cluster. Ensuite, vous exécutez un script Python qui demande un bac à sable du pool et exécute une commande dans le bac à sable. Le script utilise le client Python Agent Sandbox, une bibliothèque permettant de créer et de gérer des bacs à sable.

L'exécution de code non fiable dans un bac à sable permet de protéger votre système contre les failles potentielles du code généré par l'IA, d'accélérer le développement et d'améliorer la sécurité de vos déploiements. Pour découvrir comment Agent Sandbox sur GKE isole le code non fiable généré par l'IA, consultez À propos d'Agent Sandbox sur GKE.

Coûts

Agent Sandbox sur GKE est un logiciel Open Source que vous pouvez utiliser sans frais supplémentaires. Les tarifs de GKE s'appliquent aux ressources que vous créez, y compris aux ressources de calcul utilisées par le contrôleur Agent Sandbox.

Avant de commencer

  1. 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é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 projet Google Cloud .

  3. Activez l'API Kubernetes Engine si ce n'est pas déjà fait.

    Rôles requis pour activer les API

    Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer l'API

  4. Dans la console Google Cloud , activez Cloud Shell.

    Activer Cloud Shell

  5. Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce document.
  6. Assurez-vous de disposer d'un cluster GKE sur lequel le contrôleur Agent Sandbox est installé et le routeur Sandbox est déployé. Si ce n'est pas le cas, ne suivez que les sections suivantes de Installer Agent Sandbox sur GKE, puis revenez à ce document :
    1. Définir des variables d'environnement
    2. Créer un cluster GKE
    3. Installer Agent Sandbox
    4. Déployer le routeur de bac à sable
    Vous n'avez pas besoin de suivre les autres sections de ce document, telles que Déployer un environnement de bac à sable. Plus loin dans ce document, vous allez créer vos propres ressources SandboxTemplate et SandboxWarmPool.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des bacs à sable, demandez à votre administrateur de vous accorder 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 ci-dessous :

export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"

Voici une explication de ces variables d'environnement :

  • CLUSTER_NAME : nom de votre cluster GKE, par exemple agent-sandbox-cluster.
  • LOCATION : région ou zone Google Cloud où se trouve votre cluster GKE. Si vous utilisez un cluster Autopilot, définissez cette valeur sur la région (par exemple, us-central1). Si vous utilisez un cluster Standard, définissez cette valeur sur la zone (par exemple, us-central1-a).

Déployer un environnement de bac à sable

Cette section explique comment créer le plan de bac à sable (une ressource SandboxTemplate), vérifier le routeur réseau 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'intégralité du cycle de vie d'un bac à sable, de sa création à son 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 de bac à sable comme point d'entrée central pour l'ensemble du 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 des ressources SandboxTemplate et SandboxWarmPool

Vous allez maintenant définir la configuration de votre bac à sable en créant une ressource SandboxTemplate et une ressource SandboxWarmPool. La ressource 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 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 des bacs à sable en moins d'une seconde et d'éviter la latence de démarrage d'un bac à sable standard :

  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/v1beta1
    kind: SandboxTemplate
    metadata:
      name: python-sandbox-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/v1beta1
    kind: SandboxWarmPool
    metadata:
      name: python-sandbox-warmpool
      namespace: default
    spec:
      replicas: 2
      sandboxTemplateRef:
        name: python-sandbox-template
    
  2. Appliquez les fichiers manifestes SandboxTemplate et SandboxWarmPool :

    kubectl apply -f sandbox-template-and-pool.yaml
    
  3. Attendez que les bacs à sable du pool préprovisionné soient prêts :

    kubectl wait sandboxwarmpool python-sandbox-warmpool \
        --for=jsonpath='{.status.readyReplicas}'=2 \
        --timeout=600s
    

    Plus loin dans ce document, le client Python crée une ressource SandboxClaim. Si le client crée la revendication avant que les bacs à sable du pool ne soient prêts, le contrôleur peut créer un bac à sable pour la revendication au lieu d'en attribuer un à partir du pool. Dans un cluster Autopilot, la préparation des bacs à sable peut prendre plusieurs minutes, car GKE peut avoir besoin de créer des nœuds pour eux.

Vérifier 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é "routeur de bac à sable" pour communiquer avec les bacs à sable.

Dans 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 ordinateur local et le service Sandbox Router exécuté dans le cluster. Cette approche de tunneling évite d'avoir à utiliser une adresse IP publique ou une configuration d'entrée complexe, et simplifie l'interaction avec les bacs à sable depuis votre environnement local.

Vérifiez que le routeur de bac à sable s'exécute dans l'espace de noms agent-sandbox-system :

kubectl get deployment sandbox-router --namespace=agent-sandbox-system

Lorsque le routeur est en cours d'exécution, la colonne READY indique que toutes les instances répliquées sont prêtes, par exemple 2/2. Si la commande renvoie une erreur NotFound, déployez le routeur en suivant les étapes de la section Déployer le routeur de bac à sable.

Installer le client Python

Maintenant que les composants du cluster, comme le routeur de bac à sable, sont déployés, la dernière étape préparatoire consiste à installer le client Python Agentic Sandbox sur votre ordinateur local. Pour rappel, 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. Utilisez la même version que le contrôleur Agent Sandbox :

    pip install k8s-agent-sandbox==1.0.6
    

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. Créez un script Python nommé test_sandbox.py avec le contenu suivant :

    from k8s_agent_sandbox import SandboxClient
    from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig
    
    # Tunnels to svc/sandbox-router-svc in the agent-sandbox-system namespace.
    # cleanup=True deletes the sandbox when the script exits.
    client = SandboxClient(
        connection_config=SandboxLocalTunnelConnectionConfig(),
        cleanup=True,
    )
    
    sandbox = client.create_sandbox(warmpool="python-sandbox-warmpool", 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 de 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.commands.run() vous permet d'exécuter n'importe quelle commande shell. Agent Sandbox sur GKE 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 du code non approuvé. Cela permet à un agent IA ou à un workflow automatisé d'exécuter des tâches de manière sûre 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 qu'il soit prêt, puis utilise la méthode sandbox.commands.run() pour exécuter des commandes de shell bash dans le conteneur sécurisé. Le client capture et affiche ensuite le stdout de cette commande. Étant donné que le script définit le paramètre cleanup sur True, le client supprime le bac à sable lorsque le programme se ferme.

Lorsqu'une ressource SandboxClaim est créée, un bac à sable disponible du pool chaud est attribué à la revendication, et la revendication est marquée comme prête. La ressource SandboxWarmPool se réapprovisionne ensuite automatiquement pour maintenir le nombre d'instances répliquées configuré.

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

Exécuter des bacs à sable en production

Dans ce document, vous allez interagir avec des bacs à sable depuis l'extérieur 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 du bac à sable, et utilise la commande kubectl port-forward pour établir une connexion avec les bacs à sable. Ces étapes sont parfaitement adaptées aux scénarios de développement.

Dans un scénario de production, une application de contrôleur (comme un orchestrateur d'IA) est chargée de créer et de gérer les ressources de bac à sable. Pour utiliser Agent Sandbox sur GKE 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 configuration de l'authentification dépend de l'emplacement d'exécution de l'application du contrôleur, comme suit :

    • Si l'application du contrôleur s'exécute en tant que pod dans le même cluster, utilisez le RBAC Kubernetes ou la fédération d'identité de charge de travail pour GKE avec des stratégies IAM pour accorder au ServiceAccount Kubernetes du pod les autorisations nécessaires pour surveiller les bacs à sable ou découvrir les points de terminaison du réseau.
    • Si l'application de contrôleur s'exécute en dehors du cluster, utilisez la fédération d'identité de charge de travail ou des comptes de service IAM pour donner à l'application une identité que vous pouvez référencer dans les stratégies d'autorisation.
  • Routage : les requêtes du client Python de 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 du 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 Sandbox Router.
    • Si l'application du 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 votre code 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 ressources Google Cloud  : si le code de votre bac à sable doit envoyer des requêtes aux API Google Cloud , telles que Cloud Storage, utilisez une stratégie IAM avec la fédération d'identité de charge de travail pour GKE afin d'accorder au compte de service Kubernetes utilisé par le pod du 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 serveur de métadonnées Google Cloud (169.254.169.254), vous devez personnaliser la règle de réseau pour autoriser ce trafic.

  • Restrictions des règles de réseau : par défaut, Agent Sandbox sur GKE applique une stratégie réseau stricte sécurisée par défaut (networkPolicyManagement: Managed). Les restrictions suivantes s'appliquent à cette stratégie :

    • L'entrée est bloquée pour toutes les sources, à l'exception du routeur de bac à sable désigné (pods portant l'étiquette app: sandbox-router dans l'espace de noms agent-sandbox-system).
    • La sortie est autorisée vers l'Internet public, mais la sortie vers les plages de LAN privées (RFC 1918), le DNS de cluster interne (CoreDNS) et le serveur de métadonnées du fournisseur de services 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 la ressource SandboxTemplate. Pour obtenir des informations de configuration détaillées et des modèles personnalisables (tels que des bacs à sable sous air gap ou l'intégration de Workload Identity Federation for GKE), consultez Gestion des règles de réseau d'Agent Sandbox.

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

Par défaut, Agent Sandbox sur GKE n'applique pas de règles de sécurité aux bacs à sable. Pour appliquer les paramètres d'isolation de vos bacs à sable, appliquez la règle de validation d'admission (VAP) Kubernetes secure-sandbox-policy recommandée à partir du dépôt GitHub Agent Sandbox. Pour obtenir des instructions, consultez Appliquer la stratégie de sécurité recommandée.

La règle applique des exigences d'isolation, telles que l'obligation d'utiliser gVisor, la désactivation de hostNetwork et le blocage des volumes hostPath. La règle applique également des exigences de renforcement, telles que la suppression de toutes les fonctionnalités, l'interdiction d'ajouter de nouvelles fonctionnalités, l'obligation d'exécuter les conteneurs en tant qu'utilisateur non racine et la définition de limites de ressources. Pour obtenir la liste complète des exigences, consultez Exigences de déploiement d'Agent Sandbox sur GKE.

Modifier ou supprimer des contraintes de règle

Comme vous appliquez vous-même la règle, vous pouvez la modifier pour l'adapter à vos charges de travail. Si vos charges de travail nécessitent des exemptions de certaines règles, vous pouvez modifier la stratégie pour supprimer des contraintes spécifiques ou supprimer entièrement la liaison de stratégie. La suppression d'une contrainte réduit l'isolation fournie par la règle. Ne supprimez donc que les contraintes requises par vos charges de travail.

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

kubectl edit validatingadmissionpolicy secure-sandbox-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.

Si vous souhaitez arrêter d'appliquer la règle dans votre cluster, supprimez la liaison de règle :

kubectl delete validatingadmissionpolicybinding secure-sandbox-binding

Problèmes connus

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

Blocs de règles de sécurité lors de l'utilisation d'un maillage de services

Si vous avez appliqué la règle de sécurité recommandée et que 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, avec une erreur semblable à celle-ci :

sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'secure-sandbox-policy' with binding 'secure-sandbox-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. La règle ValidatingAdmissionPolicy secure-sandbox-policy bloque tous les ajouts de fonctionnalités dans tous les types de conteneurs.
  • Solution : comme vous gérez cette règle dans votre cluster, vous pouvez modifier le ValidatingAdmissionPolicy pour autoriser des conteneurs d'initialisation spécifiques de confiance à demander des fonctionnalités NET_ADMIN et NET_RAW. Pour savoir comment modifier ou supprimer des contraintes de règle, consultez Modifier ou supprimer des contraintes de règle. Par exemple, vous pouvez mettre à jour les expressions ou les variables de validation de la règle pour exempter les noms de conteneurs de confiance de la règle de fonctionnalités.

Latence ou délai d'expiration de sortie 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, pouvant atteindre deux minutes, lorsqu'elles tentent de se connecter à des ressources externes ou à des API Google (telles que Vertex AI ou Cloud Storage).

  • Cause : si IPv6 double pile est activé sur votre cluster GKE, la résolution DNS pour les API Google renvoie des adresses IPv4 (A) et IPv6 (AAAA). 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'un Cloud NAT ou une passerelle Internet pour IPv6, la connexion TCP cesse de répondre jusqu'à l'expiration du délai avant 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 permettre au trafic IPv6 sortant de revenir au cluster, configurez une passerelle Cloud NAT ou Internet IPv6 valide dans votre réseau VPC.
    • Privilégier IPv4 dans la charge de travail : pour privilégier la résolution DNS IPv4, configurez l'environnement d'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 compte Google Cloud , vous devez supprimer le cluster GKE que vous avez créé :

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

Étapes suivantes