agent-sandbox Kubernetes : le dépôt kubernetes-sigs/agent-sandbox propose une ressource personnalisée Sandbox et son contrôleur pour faire tourner des charges isolées, à état et à instance unique, par exemple le runtime d’un agent IA qui exécute du code généré par un modèle. Le projet est hébergé sous l’organisation Kubernetes SIGs, sous l’égide de SIG Apps. La page du dépôt affiche environ 4 400 étoiles et environ 590 forks le 29 octobre 2026, sous licence Apache 2.0.
Pour un SRE ou une équipe plateforme, la question est double. D’abord, que fait vraiment ce contrôleur et qu’est-ce qu’il ne fait pas ? Ensuite, une fois des dizaines ou des centaines de bacs à sable créés et détruits chaque minute, comment savoir s’ils démarrent vite, s’ils expirent comme prévu et si le contrôleur tient la charge ? Cet article suit le README, la documentation du dépôt et le site agent-sandbox.sigs.k8s.io.
Précision d’honnêteté : span.observer n’a pas installé agent-sandbox. Les commandes viennent du README et de la documentation du projet ; les captures reproduisent des extraits du dépôt ou en sont tirées directement.
agent-sandbox Kubernetes : ce que dit le dépôt
- Projet : le README présente agent-sandbox comme un CRD
Sandboxet un contrôleur Kubernetes développés sous SIG Apps. L’API servie estagents.x-k8s.io/v1beta1; la feuille de route indique quev1beta1est désormais la seule version servie et quev1alpha1a été retirée. - Licence et langage : Apache 2.0, vérifiée dans le fichier LICENSE du dépôt le 29 octobre 2026. Le contrôleur est écrit en Go ; des SDK Go et Python sont fournis.
- Version : la page des releases affiche v1.0.8 comme dernière version, publiée le 22 octobre 2026, avec des sorties hebdomadaires depuis fin septembre. Le chart Helm du dépôt est en version 0.1.4.
- Périmètre : le README est explicite, agent-sandbox est un orchestrateur de bacs à sable. L’isolation est déléguée à un runtime sécurisé comme gVisor ou Kata Containers, choisi par
RuntimeClassdans le gabarit de pod. Sans ce runtime, un Sandbox est un pod ordinaire. - Cas d’usage cités : runtimes d’agents IA exécutant du code non fiable, boucles d’apprentissage par renforcement, environnements de développement, notebooks, services à instance unique.
Visite des manifests
Un Sandbox ressemble à un StatefulSet de taille 1 avec un cycle de vie dédié. D’après le README, chaque Sandbox reçoit un nom d’hôte stable, peut recevoir un stockage persistant et sait être mis en pause puis repris. L’exemple de démarrage du README tient en dix lignes.

Le module extensions ajoute trois ressources dans le groupe extensions.agents.x-k8s.io/v1beta1 :
SandboxTemplate: un gabarit réutilisable pour créer des Sandboxes semblables ;SandboxWarmPool: un pool de Sandboxes préchauffés, prêts à être attribués ;SandboxClaim: la demande d’un Sandbox, servie depuis un pool quand c’est possible.
Le quickstart du dépôt explique le mécanisme : le pool crée des Sandboxes étiquetés agents.x-k8s.io/warm-pool-sandbox, une SandboxClaim adopte l’un d’eux, et le pool recrée un remplaçant pour garder son nombre de réplicas. Le même document annonce une attribution en moins de deux secondes avec un pool, contre 10 à 30 secondes sans pool (tirage d’image et démarrage du conteneur ou de la VM). Ce sont les chiffres du projet, pas une mesure de span.observer.
Ce qu’un agent fait ensuite dans le bac à sable dépend de l’image. L’exemple analytics-tool du dépôt montre un agent qui génère du code pandas et matplotlib, l’exécute dans le pod Sandbox et renvoie un graphique encodé en base64.

Installation pas à pas
Étape 1 — Prérequis
Un cluster Kubernetes et kubectl. Le guide d’installation du site propose un cluster KinD ou GKE ; le quickstart demande kubectl 1.28 ou plus et, pour une isolation réelle, un cluster avec gVisor ou Kata Containers configurés.
Étape 2 — Installer le contrôleur et les extensions
Le README recommande d’épingler une version pour la production et GitOps :
export VERSION="v1.0.8"
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/sandbox-with-extensions.yaml
Les manifests sandbox.yaml (cœur seul) et extensions.yaml existent aussi séparément. Un chart Helm est fourni dans le dossier helm/ du dépôt ; son README précise que image.tag est obligatoire et que Helm ne met pas à jour les CRD du dossier crds/ lors d’un helm upgrade.
Étape 3 — Vérifier
kubectl get crd sandboxes.agents.x-k8s.io
kubectl get deploy agent-sandbox-controller -n agent-sandbox-system
Étape 4 — Créer un Sandbox et attendre Ready
Appliquez le manifest de la capture avec une image de votre choix, puis attendez la condition Ready. La page « Status Conditions » de la documentation précise que Ready est le signal de référence : il n’existe volontairement pas de condition Running.
kubectl wait sandbox/my-sandbox --for=condition=Ready --timeout=2m
kubectl get sandbox my-sandbox -o jsonpath='{.status.conditions[?(@.type=="Ready")].reason}'
Les SDK suivent la même logique : pip install k8s-agent-sandbox pour Python, go get sigs.k8s.io/agent-sandbox/clients/go/sandbox@latest pour Go. Ils passent par le Sandbox Router, un reverse proxy HTTP optionnel qui achemine les requêtes vers le pod, utile quand le port-forward direct n’est pas disponible avec Kata ou gVisor.
Observer les bacs à sable : métriques, conditions, traces
C’est ici que le projet se distingue de beaucoup de dépôts tendance : l’observabilité est documentée. Le fichier docs/metrics.md, généré depuis le code, liste les familles de métriques Prometheus exposées par agent-sandbox-controller sur --metrics-bind-address (par défaut :8080).

Les lectures utiles pour un SLO :
agent_sandbox_creation_latency_ms: histogramme du délai entre la création d’un Sandbox et son premier passage à Ready, parnamespace,launch_typeetsandbox_template. La documentation prévient que la précision des horodatages source est à la seconde.agent_sandbox_claim_startup_latency_msetagent_sandbox_client_claim_startup_latency_ms: délai de bout en bout d’une SandboxClaim, depuis l’observation par le webhook ou depuis l’horodatage du client, jusqu’à Ready. Elles ne sont enregistrées que si la claim porte l’annotation correspondante.agent_sandbox_warmpool_size: taille de chaque pool, étiquetée parsandbox_status; un pool qui se vide pendant une rafale de claims se voit ici.agent_sandboxes: nombre de Sandboxes dans le cluster, avecready_conditionetexpired.agent_sandbox_expired_totaletagent_sandbox_finished_total: expirations surshutdownTimeet pods arrivés en phase terminale, avec la raison.agent_sandbox_suspend_latency_msetagent_sandbox_resume_latency_ms: coût d’une mise en pause et d’une reprise.
À ces familles s’ajoutent les métriques standard de controller-runtime et, si --enable-rest-client-metrics reste à true, les familles rest_client_* de client-go (latence des requêtes, retries). Pour collecter tout cela, un Collector OpenTelemetry avec un receiver Prometheus suffit ; voir le Collector OpenTelemetry sur Kubernetes et Prometheus et Dynatrace sur Kubernetes.
Côté traces, le drapeau --enable-tracing (par défaut false) active un export OTLP depuis le contrôleur. Il n’y a pas d’option pour l’adresse du Collector : l’exportateur lit les variables standard OTEL_EXPORTER_OTLP_ENDPOINT et OTEL_EXPORTER_OTLP_INSECURE. Point d’exploitation à retenir : si l’exportateur ne s’initialise pas, le contrôleur journalise l’erreur et s’arrête au démarrage. Les SDK Go et Python posent l’annotation opentelemetry.io/trace-context sur la SandboxClaim, ce qui relie la trace du client à celle du contrôleur. La documentation du SDK Python montre aussi une instrumentation locale avec pip install "k8s-agent-sandbox[tracing]" opentelemetry-distro puis opentelemetry-instrument python main.py.
Avec Dynatrace, ces métriques Prometheus et ces traces OTLP s’ingèrent de la même façon que pour tout composant Kubernetes, en SaaS (Grail, DQL) comme en Managed (sans DQL). Le contrôleur et le router sont des services à observer comme les autres ; ce qui se passe dans le bac à sable relève de l’agent lui-même, voir les garde-fous des agents IA en production.
Limites et points ouverts
- Le projet ne fournit aucune isolation lui-même : sans
runtimeClassNamegVisor ou Kata, le code généré par le modèle tourne dans un conteneur standard. Le modèle de menace du dépôt le dit clairement et recommande d’imposer le runtime via unSandboxTemplate. - D’après le modèle de menace, le mode « Managed NetworkPolicy » (ingress limité au router, egress sans réseaux RFC 1918 ni métadonnées cloud) s’applique quand on passe par un SandboxTemplate ; de même,
automountServiceAccountTokenn’est forcé àfalseque pour les Sandboxes issus d’un gabarit. UnSandboxnu doit être encadré par une admission policy. - Le guide d’installation du site déploie le router avec l’authentification désactivée et une image de staging, « pour test local uniquement » selon l’avertissement du projet.
- Supprimer les CRD supprime en cascade tous les Sandboxes du cluster, prévient le README.
- Sur la feuille de route, encore en « planned » : suspension automatique et scale to zero, serveur MCP natif, télémétrie Prometheus supplémentaire, interface web. Les sorties hebdomadaires montrent un projet jeune et actif : relisez les notes de version avant chaque mise à jour.
Bonnes pratiques
- Alertez sur
agent_sandbox_warmpool_sizeet sur le 95e centile deagent_sandbox_creation_latency_ms: ce sont vos SLI de démarrage. - Gardez
--enable-pprof-debugdésactivé en production ; la documentation signale que ces endpoints exposent le contenu du tas et les goroutines. - Fixez
shutdownTimeet desresources.limitsdans chaque gabarit : un bac à sable sans fin ni limite est un coût et un risque. - Reliez les événements Kubernetes du contrôleur à vos alertes sur nœuds, pods et quotas, en notant que
--disable-sandbox-eventsles coupe en cas de forte charge. - Pour la mise à l’échelle des pools, le dépôt contient un exemple
keda-scale-to-zero; voir KEDA autoscaling Kubernetes. Pour une autre approche des runtimes d’agents, voir NVIDIA OpenShell.
Questions fréquentes
agent-sandbox isole-t-il le code exécuté par l’agent ?
Non, pas par lui-même. Le README le décrit comme un orchestrateur qui délègue l’isolation à gVisor ou Kata Containers via RuntimeClass. Il faut configurer ce runtime dans le gabarit de pod.
Quelles métriques le contrôleur expose-t-il ?
Des métriques Prometheus sur :8080 par défaut, listées dans docs/metrics.md : latences de création, de claim, de suspension et de reprise, taille des warm pools, nombre de Sandboxes, expirations et fins de pod.
Peut-on tracer les opérations en OpenTelemetry ?
Oui. --enable-tracing active l’export OTLP du contrôleur, configuré par OTEL_EXPORTER_OTLP_ENDPOINT. Les SDK propagent le contexte de trace par l’annotation opentelemetry.io/trace-context.
Conclusion
agent-sandbox apporte à Kubernetes une primitive qui manquait aux équipes qui font tourner des agents IA : un pod isolé, nommé, suspendable, servi depuis un pool chaud. Son contrôleur publie de quoi le superviser dès le premier jour, à condition de le traiter comme un composant de production : runtime isolé imposé, métriques collectées, traces activées avec prudence. Sources : dépôt kubernetes-sigs/agent-sandbox et documentation agent-sandbox.sigs.k8s.io.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.