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
-
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'autorisationresourcemanager.projects.create. Découvrez comment attribuer des rôles.
-
Vérifiez que la facturation est activée pour votre projet Google Cloud .
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.-
Dans la console Google Cloud , activez Cloud Shell.
- Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce document.
- 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 :
- Définir des variables d'environnement
- Créer un cluster GKE
- Installer Agent Sandbox
- Déployer le routeur de bac à sable
SandboxTemplateetSandboxWarmPool.
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 exempleagent-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 :
Dans Cloud Shell, créez un fichier nommé
sandbox-template-and-pool.yamlet 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-templateAppliquez les fichiers manifestes
SandboxTemplateetSandboxWarmPool:kubectl apply -f sandbox-template-and-pool.yamlAttendez que les bacs à sable du pool préprovisionné soient prêts :
kubectl wait sandboxwarmpool python-sandbox-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sPlus 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 :
Créez et activez un environnement virtuel Python :
python3 -m venv .venv source .venv/bin/activateInstallez 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.
Créez un script Python nommé
test_sandbox.pyavec 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}")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
SandboxDirectConnectionConfigpour 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
SandboxGatewayConnectionConfigpour 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.
- Si l'application du contrôleur s'exécute dans le même cluster, utilisez la fonction
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-routerdans l'espace de nomsagent-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.- L'entrée est bloquée pour toutes les sources, à l'exception du routeur de bac à sable désigné (pods portant l'étiquette
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-initouproxy-init. Ces conteneurs d'initialisation nécessitent des fonctionnalités telles queNET_ADMINouNET_RAWpour configurer les règlesiptablespour le routage de sortie transparent. La règle ValidatingAdmissionPolicysecure-sandbox-policybloque 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
ValidatingAdmissionPolicypour autoriser des conteneurs d'initialisation spécifiques de confiance à demander des fonctionnalitésNET_ADMINetNET_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
- Découvrez comment enregistrer et restaurer Agent Sandbox sur des environnements GKE avec des instantanés de pod.
- En savoir plus sur le projet Open Source Agent Sandbox sur GitHub.
- Découvrez comment utiliser Kata Containers Open Source avec Agent Sandbox sur GKE. Kata Containers n'est pas un produit Google Cloud . Si vous installez et utilisez ce logiciel, vous êtes responsable de sa gestion et de son dépannage. L'assistance et les SLA de Google ne s'appliquent pas à Kata Containers.
- 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.