agent-sandbox Kubernetes : bacs à sable pour agents IA

agent-sandbox Kubernetes : CRD Sandbox, warm pools, isolation gVisor ou Kata, métriques Prometheus et traces OTLP pour superviser vos agents IA.
agent-sandbox Kubernetes : bacs à sable pour agents IA

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 Sandbox et un contrôleur Kubernetes développés sous SIG Apps. L’API servie est agents.x-k8s.io/v1beta1 ; la feuille de route indique que v1beta1 est désormais la seule version servie et que v1alpha1 a é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 RuntimeClass dans 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.

Manifest Sandbox minimal du README d'agent-sandbox avec apiVersion agents.x-k8s.io/v1beta1, kind Sandbox, podTemplate et image, puis trois commandes kubectl de vérification
Source : github.com

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.

Sortie de l'exemple analytics-tool du dépôt agent-sandbox : code Python généré par l'agent, exécuté dans le Sandbox, puis graphique en barres des montants d'achat par État
Source : raw.githubusercontent.com

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).

Extrait de docs/metrics.md d'agent-sandbox avec huit métriques du contrôleur et leur type, puis extrait de docs/configuration.md avec les options metrics-bind-address, enable-tracing, enable-rest-client-metrics et la variable OTEL_EXPORTER_OTLP_ENDPOINT
Source : github.com

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, par namespace, launch_type et sandbox_template. La documentation prévient que la précision des horodatages source est à la seconde.
  • agent_sandbox_claim_startup_latency_ms et agent_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 par sandbox_status ; un pool qui se vide pendant une rafale de claims se voit ici.
  • agent_sandboxes : nombre de Sandboxes dans le cluster, avec ready_condition et expired.
  • agent_sandbox_expired_total et agent_sandbox_finished_total : expirations sur shutdownTime et pods arrivés en phase terminale, avec la raison.
  • agent_sandbox_suspend_latency_ms et agent_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 runtimeClassName gVisor 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 un SandboxTemplate.
  • 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, automountServiceAccountToken n’est forcé à false que pour les Sandboxes issus d’un gabarit. Un Sandbox nu 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_size et sur le 95e centile de agent_sandbox_creation_latency_ms : ce sont vos SLI de démarrage.
  • Gardez --enable-pprof-debug désactivé en production ; la documentation signale que ces endpoints exposent le contenu du tas et les goroutines.
  • Fixez shutdownTime et des resources.limits dans 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-events les 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.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
Migrer extensions JMX et PMI EF1 vers Extensions 2.0 avant juillet 2027

Migrer extensions JMX et PMI EF1 vers Extensions 2.0 avant juillet 2027

Next Post
Syft générateur SBOM : inventorier vos images de conteneurs

Syft générateur SBOM : inventorier vos images de conteneurs

Related Posts