Ce document explique comment installer le contrôleur Agent Sandbox Open Source sur un cluster Google Kubernetes Engine (GKE) pour exécuter des charges de travail en bac à sable dans des pods Kubernetes dédiés. Vous apprendrez également à créer un environnement de bac à sable sur le cluster pour exécuter du code non approuvé en toute sécurité.
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.
Choisir entre une architecture basée sur des pods et une architecture basée sur des acteurs
Avant d'installer Agent Sandbox sur GKE, déterminez l'architecture GKE qui convient à vos charges de travail d'agent IA :
- Agent Substrate sur GKE (basé sur les acteurs) : utilisez cette architecture pour la plupart des charges de travail agentives, en particulier les agents avec état qui sont fréquemment suspendus et repris. Les agents actifs partagent un pool de pods chauds au lieu de conserver un pod dédié par agent. Vous pouvez ainsi exécuter plus d'agents sur moins de nœuds. Agent Substrate sur GKE permet de suspendre et de reprendre automatiquement les charges de travail inactives, et de restaurer les agents à partir du stockage en moins d'une seconde. En revanche, Agent Sandbox sur GKE nécessite de créer manuellement des instantanés de pods, et vous devez créer du code d'application pour détecter l'inactivité et enregistrer la progression de l'agent. Agent Substrate sur GKE nécessite un cluster GKE Standard. Pour en savoir plus, consultez À propos d'Agent Substrate sur GKE. Pour installer cette option, consultez Installer Agent Substrate sur GKE.
- Agent Sandbox sur GKE (basé sur des pods) : utilisez cette architecture, que vous installez dans ce document, lorsque chaque agent a besoin d'un pod Kubernetes dédié sur un cluster GKE Autopilot ou Standard. Choisissez cette option pour les agents ou les charges de travail actifs en continu qui nécessitent l'un des éléments suivants :
- Les API Kubernetes déclaratives, telles que les ressources personnalisées
SandboxetSandboxClaim - Le schéma Kubernetes
PodSpeccomplet, y compris les conteneurs side-car et d'initialisation personnalisés - Accès direct aux accélérateurs matériels, tels que les GPU ou les TPU
- Clusters GKE Autopilot
- Les API Kubernetes déclaratives, telles que les ressources personnalisées
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.
Pour éviter des frais inutiles, veillez à désactiver GKE ou à supprimer le projet une fois que vous avez terminé ce document.
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 Google 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.
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"
export AGENT_SANDBOX_VERSION="v1.0.6"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"
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 dans laquelle votre cluster GKE est créé. Si vous créez un cluster Autopilot, définissez-le sur la région (par exemple,us-central1). Les clusters Autopilot sont toujours régionaux. Si vous créez un cluster Standard, définissez cette option sur la zone (par exemple,us-central1-a). Pour réduire les coûts, ce document crée un cluster zonal, qui utilise moins de nœuds qu'un cluster régional.AGENT_SANDBOX_VERSION: version du contrôleur Agent Sandbox Open Source à installer. Ce document utilise la version 1.0.6. Pour voir les autres versions, accédez à la page des versions d'Agent Sandbox.NODE_POOL_NAME: nom du pool de nœuds qui exécutera les charges de travail en bac à sable (par exemple,agent-sandbox-pool). Cette variable n'est requise que si vous créez un cluster GKE Standard.MACHINE_TYPE: type de machine des nœuds du pool de nœuds par défaut de votre cluster et du pool de nœuds gVisor (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. Cette variable n'est requise que si vous créez un cluster GKE Standard.
Créer un cluster GKE
Agent Sandbox sur GKE isole les charges de travail en bac à sable à l'aide de gVisor ou de microVMs. Si vous ne spécifiez pas d'environnement d'exécution de bac à sable, les bacs à sable s'exécutent sans isolation du noyau, ce que nous ne recommandons pas pour le code non approuvé. Ce document utilise gVisor. Les clusters Autopilot activent gVisor automatiquement. Dans les clusters standards, vous créez un pool de nœuds sur lequel gVisor est activé. Pour utiliser des microVM à la place, consultez Activer le type de bac à sable microVM. La règle de sécurité recommandée n'autorise que gVisor. Elle rejette donc les bacs à sable qui utilisent des microVM.
Autopilot
Pour créer un cluster Autopilot, assurez-vous que la variable d'environnement LOCATION est définie sur une région, telle que us-central1, puis exécutez la commande suivante :
gcloud container clusters create-auto ${CLUSTER_NAME} \
--location=${LOCATION}
Standard
Pour créer un cluster standard, vous devez créer le cluster, puis ajouter un pool de nœuds avec gVisor activé. Pour réduire les coûts, ce document crée un cluster zonal avec un seul nœud par pool.
Définissez la variable d'environnement
LOCATIONsur une zone, par exempleus-central1-a:export LOCATION="us-central1-a"Créez le cluster :
gcloud container clusters create ${CLUSTER_NAME} \ --location=${LOCATION} \ --machine-type=${MACHINE_TYPE} \ --num-nodes=1Créez un pool de nœuds distinct avec gVisor activé :
gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --machine-type=${MACHINE_TYPE} \ --location=${LOCATION} \ --num-nodes=1 \ --image-type=cos_containerd \ --sandbox=type=gvisorPour utiliser des microVM au lieu de gVisor, créez le pool de nœuds comme décrit dans Activer le type de bac à sable microVM. Le reste de ce document utilise gVisor.
Pour utiliser un cluster Standard existant, assurez-vous qu'il inclut un pool de nœuds sur lequel gVisor est activé. Si le cluster ne dispose pas d'un tel pool de nœuds, créez-en un en exécutant la commande gcloud container node-pools create précédente.
Pour permettre à l'outil de ligne de commande kubectl de se connecter au cluster, obtenez les identifiants du cluster :
gcloud container clusters get-credentials ${CLUSTER_NAME} \
--location=${LOCATION}
Installer Agent Sandbox
Pour installer Agent Sandbox, appliquez un fichier manifeste de version à partir du dépôt GitHub Agent Sandbox. Le fichier manifeste sandbox-with-extensions.yaml installe le contrôleur Agent Sandbox et les CustomResourceDefinitions pour la ressource Sandbox et pour les ressources d'extension SandboxTemplate, SandboxClaim et SandboxWarmPool.
Appliquez le fichier manifeste de la version :
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yamlLe fichier manifeste crée l'espace de noms
agent-sandbox-systemet déploie le contrôleur dans cet espace de noms.Attendez que le contrôleur soit prêt :
kubectl rollout status deployment/agent-sandbox-controller \ --namespace=agent-sandbox-system \ --timeout=120s
Vous pouvez également installer Agent Sandbox à l'aide de Helm. Pour obtenir des instructions, consultez le fichier README du chart Helm Agent Sandbox.
Vérifier l'installation
Vérifiez que les CustomResourceDefinitions d'Agent Sandbox sont installées :
kubectl get crd \ sandboxes.agents.x-k8s.io \ sandboxtemplates.extensions.agents.x-k8s.io \ sandboxclaims.extensions.agents.x-k8s.io \ sandboxwarmpools.extensions.agents.x-k8s.ioLe résultat liste les quatre CustomResourceDefinitions.
Vérifiez que le contrôleur est en cours d'exécution :
kubectl get deployment agent-sandbox-controller \ --namespace=agent-sandbox-systemLorsque le contrôleur est en cours d'exécution, la colonne
READYaffiche1/1.
Appliquer la stratégie de sécurité recommandée
Par défaut, Agent Sandbox sur GKE ne limite pas la configuration des pods qui exécutent vos bacs à sable. Pour appliquer les paramètres d'isolation de vos bacs à sable, appliquez la règle secure-sandbox-policy
ValidatingAdmissionPolicy recommandée à partir du dépôt GitHub Agent Sandbox. Cette règle refuse toute ressource Sandbox qui ne répond pas aux exigences de déploiement d'Agent Sandbox sur GKE.
Appliquez la règle :
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/examples/policy/vap/secure-sandbox-policy.yamlAppliquez la liaison de stratégie. La liaison applique la règle dans tous les espaces de noms, à l'exception des espaces de noms système, tels que
kube-system:kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/examples/policy/vap/secure-sandbox-binding.yaml
La règle valide Sandbox ressources. Lorsque vous créez une ressource SandboxWarmPool ou SandboxClaim, le contrôleur crée des ressources Sandbox à partir d'une ressource SandboxTemplate. Si le modèle ne répond pas aux exigences, la règle rejette la ressource Sandbox et l'erreur s'affiche dans les journaux du contrôleur. Pour afficher les journaux, exécutez la commande suivante :
kubectl logs deployment/agent-sandbox-controller \
--namespace=agent-sandbox-system
Vous êtes propriétaire de cette règle et vous pouvez la modifier pour l'adapter à vos charges de travail. Pour en savoir plus, consultez Stratégies de sécurité du bac à sable.
Exigences de déploiement d'Agent Sandbox sur GKE
Si vous appliquez la règle de sécurité recommandée, vos fichiers manifestes de charge de travail, tels qu'une ressource Sandbox ou SandboxTemplate, doivent inclure des paramètres de sécurité et de configuration spécifiques. Si une ressource Sandbox ne répond pas à ces exigences, le contrôleur d'admission la rejette. Les exigences relatives aux conteneurs s'appliquent à tous les conteneurs du pod, y compris les conteneurs d'initialisation et les conteneurs éphémères.
Configuration requise
Votre fichier manifeste de déploiement doit inclure les paramètres suivants :
runtimeClassName: gvisor: garantit que le pod s'exécute dans un bac à sable gVisor. La règle rejette les bacs à sable qui utilisent un autre environnement d'exécution, y compris les microVM.automountServiceAccountToken: false: empêche le pod d'installer automatiquement le jeton du compte de service par défaut.securityContext.runAsNonRoot: true: garantit que le conteneur ne s'exécute pas en tant qu'utilisateur racine.securityContext.capabilities.drop: ["ALL"]: supprime toutes les fonctionnalités Linux du conteneur.resources.limits: vous devez spécifier des limites de processeur et de mémoire pour éviter d'éventuels scénarios de déni de service (DoS).nodeSelector: doit ciblersandbox.gke.io/runtime: gvisor.tolerations: doit inclure une tolérance pour le rejetsandbox.gke.io/runtime=gvisor:NoSchedule.
Configuration interdite
Votre fichier manifeste de déploiement ne doit pas inclure les éléments suivants :
hostNetwork: true,hostPID: trueouhostIPC: true.privileged: truedans les contextes de sécurité des conteneurs.procMount: Unmaskeddans les contextes de sécurité des conteneurs.HostPathvolumes.- Ajout de fonctionnalités (
capabilities.add). hostPortparamètre.- sysctls personnalisés.
- Volumes projetés pour les jetons ou certificats de compte de service.
Déployer le routeur de bac à sable (facultatif)
Le routeur de bac à sable est un proxy HTTP qui achemine les requêtes des clients, comme le client Python Agent Sandbox, vers les pods qui exécutent vos bacs à sable. Si vous prévoyez d'utiliser le client Python, par exemple comme décrit dans Isoler l'exécution de code d'IA avec Agent Sandbox sur GKE, déployez le routeur.
Vous déployez le routeur dans l'espace de noms agent-sandbox-system. Par défaut, la règle de réseau qu'Agent Sandbox sur GKE crée pour chaque ressource SandboxTemplate n'autorise le trafic entrant vers les bacs à sable qu'à partir des pods de routeur de cet espace de noms.
Créez le compte de service du routeur et les autorisations RBAC qui permettent au routeur de rechercher des pods de bac à sable :
kubectl apply \ -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/serviceaccount.yaml \ -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/rbac.yamlDéployez le routeur. La commande suivante définit l'image du routeur sur la même version que le contrôleur :
curl -sSL https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/deployment.yaml \ | sed "s|sandbox-router-go:latest|sandbox-router-go:${AGENT_SANDBOX_VERSION}|" \ | kubectl apply -f -Créez le service du routeur :
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/service.yamlAttendez que le routeur soit prêt :
kubectl rollout status deployment/sandbox-router \ --namespace=agent-sandbox-system \ --timeout=120s
Cette configuration de routeur est destinée au développement et aux tests. Pour connaître les paramètres de production, tels que TLS, le nombre d'instances répliquées et les règles de réseau pour le routeur, consultez le fichier README sur le déploiement du routeur de bac à sable.
Déployer un environnement de bac à sable
Nous vous recommandons de déployer un environnement de bac à sable en définissant une ressource SandboxTemplate et de garder les instances préchauffées prêtes à l'aide d'une ressource SandboxWarmPool. Vous pouvez ensuite demander une instance à partir de ce pool de préchauffage à l'aide d'une ressource SandboxClaim. Vous pouvez également créer une ressource Sandbox directement, mais cette approche n'est pas compatible avec les pools de préchauffage.
SandboxTemplate, SandboxWarmPool, SandboxClaim et Sandbox sont des ressources personnalisées Kubernetes.
Recommandé : Créer des ressources SandboxTemplate et SandboxWarmPool
La ressource SandboxTemplate sert de plan réutilisable. La ressource SandboxWarmPool permet de s'assurer qu'un nombre spécifié de bacs à sable préchauffés sont toujours en cours d'exécution et prêts à être revendiqués. L'utilisation de cette ressource personnalisée réduit la latence de démarrage.
Pour déployer un environnement en bac à sable en créant les ressources SandboxTemplate et SandboxWarmPool, procédez comme suit :
Dans Cloud Shell, créez un fichier nommé
sandbox-template.yamlet contenant ce qui suit :apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxTemplate metadata: name: python-runtime-template namespace: default spec: podTemplate: metadata: labels: sandbox-type: python-runtime spec: runtimeClassName: gvisor # Required 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: runtime image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 resources: requests: cpu: "250m" memory: "512Mi" limits: cpu: "500m" memory: "1Gi" # Required securityContext: capabilities: drop: ["ALL"] # Required restartPolicy: OnFailureAppliquez le fichier manifeste
SandboxTemplate:kubectl apply -f sandbox-template.yamlCréez un fichier nommé
sandbox-warmpool.yamlavec le contenu suivant :apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxWarmPool metadata: name: python-runtime-warmpool namespace: default labels: app: python-runtime-warmpool spec: replicas: 2 sandboxTemplateRef: # This must match the name of the SandboxTemplate. name: python-runtime-templateAppliquez le fichier manifeste
SandboxWarmPool:kubectl apply -f sandbox-warmpool.yamlAttendez que les bacs à sable du pool préprovisionné soient prêts :
kubectl wait sandboxwarmpool python-runtime-warmpool \ --for=jsonpath='{.status.readyReplicas}'=2 \ --timeout=600sSi vous créez une ressource
SandboxClaimavant 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, les bacs à sable peuvent mettre plusieurs minutes à être prêts, car GKE peut avoir besoin de créer des nœuds pour eux.
Créer une ressource SandboxClaim
La ressource SandboxClaim demande un bac à sable au pool de préchauffage. Comme vous avez créé un pool chaud, le contrôleur attribue un bac à sable en cours d'exécution du pool à la revendication au lieu d'en créer un nouveau.
Pour demander un bac à sable du pool de préchauffage en créant une ressource SandboxClaim, procédez comme suit :
Créez un fichier nommé
sandbox-claim.yamlavec le contenu suivant :apiVersion: extensions.agents.x-k8s.io/v1beta1 kind: SandboxClaim metadata: name: sandbox-claim namespace: default spec: warmPoolRef: # This must match the name of the SandboxWarmPool. name: python-runtime-warmpoolAppliquez le fichier manifeste
SandboxClaim:kubectl apply -f sandbox-claim.yamlVérifiez que le bac à sable, la revendication et le pool de préchauffage sont prêts :
kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
Alternative : Créer directement une ressource Sandbox
Si vous n'avez pas besoin des temps de démarrage rapides fournis par les pools préchauffés, vous pouvez déployer une ressource Sandbox directement sans utiliser de modèles.
Pour déployer un environnement de bac à sable en créant directement une ressource Sandbox, procédez comme suit :
Créez un fichier nommé
sandbox.yamlavec le contenu suivant :apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: sandbox-example-2 spec: podTemplate: metadata: labels: sandbox: sandbox-example spec: runtimeClassName: gvisor restartPolicy: OnFailure automountServiceAccountToken: false # Required securityContext: runAsNonRoot: true # Required runAsUser: 1000 # Required if image defaults to root (for example, busybox) nodeSelector: sandbox.gke.io/runtime: gvisor tolerations: - key: "sandbox.gke.io/runtime" value: "gvisor" effect: "NoSchedule" # Required containers: - name: my-container image: busybox command: ["/bin/sh", "-c"] args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"] securityContext: capabilities: drop: ["ALL"] # Required allowPrivilegeEscalation: false resources: limits: cpu: "100m" memory: "128Mi" # RequiredAppliquez le fichier manifeste
Sandbox:kubectl apply -f sandbox.yamlVérifiez que le bac à sable est en cours d'exécution :
kubectl get sandbox
Mettre à niveau Agent Sandbox
Pour mettre à niveau Agent Sandbox, appliquez le fichier manifeste de la nouvelle version :
export AGENT_SANDBOX_VERSION="NEW_VERSION"
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yaml
Remplacez NEW_VERSION par la version que vous souhaitez installer, par exemple une version listée sur la page des versions d'Agent Sandbox.
Avant de procéder à la mise à niveau, consultez les notes de version de la nouvelle version. Si votre cluster exécute une version d'Agent Sandbox antérieure à la version 1.0.0, vous devez migrer vos ressources vers l'API v1beta1 avant d'effectuer la mise à niveau, car la version 1.0.0 a supprimé l'API v1alpha1. Pour obtenir des instructions, consultez le guide de migration de l'API.
Si vous avez déployé le routeur Sandbox ou appliqué la règle de sécurité recommandée, répétez ces étapes pour la nouvelle version.
Désinstaller Agent Sandbox
Vérifiez si des ressources Agent Sandbox sont toujours utilisées :
kubectl get sandboxes,sandboxclaims,sandboxwarmpools,sandboxtemplates \ --all-namespacesSi vous avez appliqué la stratégie de sécurité recommandée, supprimez la liaison de stratégie et la stratégie :
kubectl delete validatingadmissionpolicybinding secure-sandbox-binding kubectl delete validatingadmissionpolicy secure-sandbox-policySi vous avez déployé le routeur Sandbox, supprimez ses ressources RBAC au niveau du cluster :
kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/${AGENT_SANDBOX_VERSION}/sandbox-router/deploy/rbac.yamlLes autres ressources du routeur se trouvent dans l'espace de noms
agent-sandbox-system, qui sera supprimé à l'étape suivante.Pour supprimer le contrôleur Agent Sandbox, son espace de noms et ses CustomResourceDefinitions, supprimez le fichier manifeste de la version que vous avez installée :
kubectl delete -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yaml
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=${LOCATION} \
--quiet
Si vous avez créé un cluster Autopilot, l'emplacement correspond à la région (par exemple, us-central1). Si vous avez créé un cluster Standard, l'emplacement correspond à la zone (par exemple, us-central1-a).
Étapes suivantes
- Découvrez comment enregistrer et restaurer Agent Sandbox dans des environnements GKE avec des instantanés de pods.
- Découvrez la technologie sous-jacente utilisée par Agent Sandbox sur GKE.
- En savoir plus sur la sécurité de GKE
- Découvrez 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.