agent-sandbox Kubernetes: el repositorio kubernetes-sigs/agent-sandbox propone un recurso personalizado Sandbox y su controlador para ejecutar cargas aisladas, con estado y de instancia única, por ejemplo el runtime de un agente de IA que ejecuta código generado por un modelo. El proyecto está alojado en la organización Kubernetes SIGs, bajo el paraguas de SIG Apps. La página del repositorio muestra unas 4400 estrellas y unos 590 forks el 29 de octubre de 2026, con licencia Apache 2.0.
Para un SRE o un equipo de plataforma la pregunta es doble. Primero, ¿qué hace realmente este controlador y qué no hace? Después, cuando se crean y destruyen decenas o cientos de sandboxes cada minuto, ¿cómo saber si arrancan rápido, si expiran como está previsto y si el controlador aguanta la carga? Este artículo sigue el README, la documentación del repositorio y el sitio agent-sandbox.sigs.k8s.io.
Una precisión de honestidad: span.observer no ha instalado agent-sandbox. Los comandos vienen del README y de la documentación del proyecto; las capturas reproducen extractos del repositorio o se han tomado directamente de él.
agent-sandbox Kubernetes: qué dice el repositorio
- Proyecto: el README presenta agent-sandbox como un CRD
Sandboxy un controlador de Kubernetes desarrollados bajo SIG Apps. La API servida esagents.x-k8s.io/v1beta1; la hoja de ruta indica quev1beta1es ahora la única versión servida y quev1alpha1se ha retirado. - Licencia y lenguaje: Apache 2.0, verificada en el archivo LICENSE del repositorio el 29 de octubre de 2026. El controlador está escrito en Go; se proporcionan SDK para Go y Python.
- Versión: la página de releases muestra v1.0.8 como última versión, publicada el 22 de octubre de 2026, con lanzamientos semanales desde finales de septiembre. El chart de Helm del repositorio está en la versión 0.1.4.
- Alcance: el README es explícito, agent-sandbox es un orquestador de sandboxes. El aislamiento se delega en un runtime seguro como gVisor o Kata Containers, elegido mediante
RuntimeClassen la plantilla de pod. Sin ese runtime, un Sandbox es un pod normal. - Casos de uso citados: runtimes de agentes de IA que ejecutan código no confiable, bucles de aprendizaje por refuerzo, entornos de desarrollo, notebooks, servicios de instancia única.
Recorrido por los manifests
Un Sandbox se parece a un StatefulSet de tamaño 1 con un ciclo de vida propio. Según el README, cada Sandbox recibe un nombre de host estable, puede recibir almacenamiento persistente y sabe pausarse y reanudarse. El ejemplo de inicio del README cabe en diez líneas.

El módulo extensions añade tres recursos en el grupo extensions.agents.x-k8s.io/v1beta1:
SandboxTemplate: una plantilla reutilizable para crear Sandboxes parecidos;SandboxWarmPool: un pool de Sandboxes precalentados, listos para asignarse;SandboxClaim: la petición de un Sandbox, servida desde un pool cuando es posible.
El quickstart del repositorio explica el mecanismo: el pool crea Sandboxes etiquetados con agents.x-k8s.io/warm-pool-sandbox, una SandboxClaim adopta uno de ellos y el pool crea un sustituto para mantener su número de réplicas. El mismo documento anuncia una asignación en menos de dos segundos con pool, frente a 10 a 30 segundos sin pool (descarga de la imagen y arranque del contenedor o de la VM). Son cifras del proyecto, no una medición de span.observer.
Lo que el agente hace después dentro del sandbox depende de la imagen. El ejemplo analytics-tool del repositorio muestra un agente que genera código con pandas y matplotlib, lo ejecuta en el pod Sandbox y devuelve un gráfico codificado en base64.

Instalación paso a paso
Paso 1: requisitos
Un clúster de Kubernetes y kubectl. La guía de instalación del sitio propone un clúster KinD o GKE; el quickstart pide kubectl 1.28 o superior y, para un aislamiento real, un clúster con gVisor o Kata Containers configurados.
Paso 2: instalar el controlador y las extensiones
El README recomienda fijar una versión para producción y GitOps:
export VERSION="v1.0.8"
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/sandbox-with-extensions.yaml
Los manifests sandbox.yaml (solo el núcleo) y extensions.yaml también existen por separado. Se proporciona un chart de Helm en la carpeta helm/ del repositorio; su README precisa que image.tag es obligatorio y que Helm no actualiza los CRD de la carpeta crds/ durante un helm upgrade.
Paso 3: verificar
kubectl get crd sandboxes.agents.x-k8s.io
kubectl get deploy agent-sandbox-controller -n agent-sandbox-system
Paso 4: crear un Sandbox y esperar a Ready
Aplica el manifest de la captura con una imagen de tu elección y espera la condición Ready. La página «Status Conditions» de la documentación precisa que Ready es la señal de referencia: deliberadamente no existe una condición Running.
kubectl wait sandbox/my-sandbox --for=condition=Ready --timeout=2m
kubectl get sandbox my-sandbox -o jsonpath='{.status.conditions[?(@.type=="Ready")].reason}'
Los SDK siguen la misma lógica: pip install k8s-agent-sandbox para Python, go get sigs.k8s.io/agent-sandbox/clients/go/sandbox@latest para Go. Pasan por el Sandbox Router, un reverse proxy HTTP opcional que encamina las peticiones hacia el pod, útil cuando el port-forward directo no está disponible con Kata o gVisor.
Observar los sandboxes: métricas, condiciones, trazas
Aquí es donde el proyecto se distingue de muchos repositorios de moda: la observabilidad está documentada. El archivo docs/metrics.md, generado a partir del código, lista las familias de métricas de Prometheus que expone agent-sandbox-controller en --metrics-bind-address (por defecto :8080).

Las lecturas útiles para un SLO:
agent_sandbox_creation_latency_ms: histograma del tiempo entre la creación de un Sandbox y su primer paso a Ready, pornamespace,launch_typeysandbox_template. La documentación avisa de que la precisión de las marcas de tiempo de origen es de un segundo.agent_sandbox_claim_startup_latency_msyagent_sandbox_client_claim_startup_latency_ms: tiempo de extremo a extremo de una SandboxClaim, desde la observación por el webhook o desde la marca de tiempo del cliente, hasta Ready. Solo se registran si la claim lleva la anotación correspondiente.agent_sandbox_warmpool_size: tamaño de cada pool, etiquetado consandbox_status; un pool que se vacía durante una ráfaga de claims se ve aquí.agent_sandboxes: número de Sandboxes en el clúster, conready_conditionyexpired.agent_sandbox_expired_totalyagent_sandbox_finished_total: expiraciones porshutdownTimey pods que llegan a una fase terminal, con el motivo.agent_sandbox_suspend_latency_msyagent_sandbox_resume_latency_ms: coste de una pausa y de una reanudación.
A estas familias se suman las métricas estándar de controller-runtime y, si --enable-rest-client-metrics se mantiene en true, las familias rest_client_* de client-go (latencia de las peticiones, reintentos). Para recoger todo esto basta un Collector de OpenTelemetry con un receiver de Prometheus; consulta el Collector de OpenTelemetry en Kubernetes y Prometheus y Dynatrace en Kubernetes.
En cuanto a las trazas, el flag --enable-tracing (por defecto false) activa una exportación OTLP desde el controlador. No hay opción para la dirección del Collector: el exportador lee las variables estándar OTEL_EXPORTER_OTLP_ENDPOINT y OTEL_EXPORTER_OTLP_INSECURE. Punto operativo a recordar: si el exportador no se inicializa, el controlador registra el error y se detiene al arrancar. Los SDK de Go y Python ponen la anotación opentelemetry.io/trace-context en la SandboxClaim, lo que enlaza la traza del cliente con la del controlador. La documentación del SDK de Python muestra además una instrumentación local con pip install "k8s-agent-sandbox[tracing]" opentelemetry-distro y después opentelemetry-instrument python main.py.
Con Dynatrace, estas métricas de Prometheus y estas trazas OTLP se ingieren igual que las de cualquier componente de Kubernetes, tanto en SaaS (Grail, DQL) como en Managed (sin DQL). El controlador y el router son servicios que observar como cualquier otro; lo que ocurre dentro del sandbox corresponde al propio agente, consulta las barreras de seguridad de los agentes de IA en producción.
Límites y puntos abiertos
- El proyecto no proporciona ningún aislamiento por sí mismo: sin
runtimeClassNamegVisor o Kata, el código generado por el modelo se ejecuta en un contenedor estándar. El modelo de amenazas del repositorio lo dice claramente y recomienda imponer el runtime mediante unSandboxTemplate. - Según el modelo de amenazas, el modo «Managed NetworkPolicy» (ingress limitado al router, egress sin redes RFC 1918 ni metadatos de la nube) se aplica cuando se pasa por un SandboxTemplate; del mismo modo,
automountServiceAccountTokensolo se fuerza afalseen los Sandboxes creados desde una plantilla. UnSandboxsuelto debe controlarse con una admission policy. - La guía de instalación del sitio despliega el router con la autenticación desactivada y una imagen de staging, «solo para pruebas locales» según la advertencia del proyecto.
- Eliminar los CRD elimina en cascada todos los Sandboxes del clúster, avisa el README.
- En la hoja de ruta, todavía en «planned»: suspensión automática y escalado a cero, servidor MCP nativo, telemetría de Prometheus adicional, interfaz web. Los lanzamientos semanales muestran un proyecto joven y activo: relee las notas de versión antes de cada actualización.
Buenas prácticas
- Alerta sobre
agent_sandbox_warmpool_sizey sobre el percentil 95 deagent_sandbox_creation_latency_ms: son tus SLI de arranque. - Mantén
--enable-pprof-debugdesactivado en producción; la documentación señala que esos endpoints exponen el contenido del heap y las goroutines. - Fija
shutdownTimeyresources.limitsen cada plantilla: un sandbox sin fin ni límite es un coste y un riesgo. - Enlaza los eventos de Kubernetes del controlador con tus alertas sobre nodos, pods y cuotas, teniendo en cuenta que
--disable-sandbox-eventslos corta en caso de carga alta. - Para escalar los pools, el repositorio contiene un ejemplo
keda-scale-to-zero; consulta KEDA autoescalado Kubernetes. Para otro enfoque de los runtimes de agentes, consulta NVIDIA OpenShell.
Preguntas frecuentes
¿Aísla agent-sandbox el código que ejecuta el agente?
No, no por sí mismo. El README lo describe como un orquestador que delega el aislamiento en gVisor o Kata Containers mediante RuntimeClass. Hay que configurar ese runtime en la plantilla de pod.
¿Qué métricas expone el controlador?
Métricas de Prometheus en :8080 por defecto, listadas en docs/metrics.md: latencias de creación, de claim, de suspensión y de reanudación, tamaño de los warm pools, número de Sandboxes, expiraciones y fines de pod.
¿Se pueden trazar las operaciones con OpenTelemetry?
Sí. --enable-tracing activa la exportación OTLP del controlador, configurada con OTEL_EXPORTER_OTLP_ENDPOINT. Los SDK propagan el contexto de traza mediante la anotación opentelemetry.io/trace-context.
Conclusión
agent-sandbox aporta a Kubernetes una primitiva que les faltaba a los equipos que ejecutan agentes de IA: un pod aislado, con nombre, suspendible, servido desde un pool caliente. Su controlador publica lo necesario para supervisarlo desde el primer día, siempre que se trate como un componente de producción: runtime aislado impuesto, métricas recogidas, trazas activadas con prudencia. Fuentes: repositorio kubernetes-sigs/agent-sandbox y documentación en agent-sandbox.sigs.k8s.io.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión.