Serie: Explorando una forma segura de correr DeepSeek Harness en Kubernetes — Parte 2 de 2.
Anterior: Parte 1: la imagen, su contrato de runtime y el sandbox interno.
Un agente de código para uso personal se levanta en un fin de semana. Uno por usuario, con estado persistente, UI web, SSO y una factura mensual que puedas mostrar sin cambiar de tema, ya es una mini-plataforma. Eso es lo que armé en sredevopsorg/deepseek-kubernetes-sandbox: una instancia de DeepSeek Harness Web (DSH) por persona, aprovisionada desde un warm pool, suspendida cuando nadie la usa y despertada sola cuando su dueño vuelve.
La base es kubernetes-sigs/agent-sandbox, el proyecto del SIG de Kubernetes que aporta el CRD Sandbox en agents.x-k8s.io/v1beta1 junto con las extensiones SandboxTemplate, SandboxClaim y SandboxWarmPool en extensions.agents.x-k8s.io/v1beta1. El repo fija v1.0.10 en versions.env, y de ahí sale todo lo que sigue.
Una instancia de DSH por usuario, aprovisionada en un par de segundos
El punto de partida fue el ejemplo upstream Hermes agents-as-a-service, que destila el patrón: un template, un warm pool, un claim diminuto por usuario y operatingMode como perilla de costo. Cambié el agente por mi build de DSH y le puse al frente un gateway en Python que enruta tráfico y controla el ciclo de vida de cada sandbox.
Lo que queda en pie:
- Estado por usuario en un PVC de 5 Gi. Conversaciones, sesiones, configuración y el workspace del agente sobreviven a cualquier reinicio del pod.
- Aprovisionamiento en torno a 2 s cuando hay repuesto en el pool. Si el pool está seco, el claim espera y el registro responde
202 con estado Waking. - Suspensión por inactividad y wake-on-connect. El pod se va cuando nadie lo usa; la primera petición del usuario lo trae de vuelta.
- Costo atado al uso. Sin pod no hay cómputo; el PVC sigue ahí y se paga, que es más barato que un agente encendido 24/7.
⚠️
Las instrucciones paso a paso viven en el
README del ejemplo. Acá van las decisiones y las trampas, que nunca caben en un quickstart.
Tres capas y una sola puerta de entrada
La plataforma se entrega como una base de Kustomize con overlays:
- Recursos — namespace,
SandboxTemplate, warm pool, claims de ejemplo y gateway; el Secret del proveedor se crea en cada instalación, no vive en el repo. - Servicio — el gateway en Starlette que vuelve usable todo esto desde el navegador: registro, sesiones, proxy HTTP y WebSocket, wake-on-connect y barrido por inactividad.
- Exposición — un único punto de entrada: Ingress de Traefik, o Gateway API con SSO de GitHub vía
oauth2-proxy.
manifests/
+-- base/ # namespace, template, warm pool, claims, gateway
+-- optional/ # componente aditivo: la NetworkPolicy de los sandboxes
+-- exposure/ # overlays ingress/ y gateway-api-sso/ (elige solo uno)
+-- local/ # lo específico de tu clúster, nunca en base/
kubectl apply -k manifests/base deja la plataforma sin acceso externo. Cada overlay de exposición incluye la base y la parcha, así que aplicas uno solo: con los dos activos abres una segunda ruta que no pasa por el SSO, y el gateway honra la cabecera de identidad de cualquiera que la mande. Eso es suplantación de usuarios, no un registro abierto. El overlay de Ingress deja COOKIE_SECURE=true y borra ALLOW_INSECURE_COOKIES; el de SSO hace lo mismo y suma AUTH_PROXY_HEADER y TRUSTED_PROXY_HOPS.
Nunca corras kubectl delete -k sobre un overlay: el render incluye la base completa, o sea el namespace y todo lo que vive adentro. Para cambiar de variante, borra por nombre los archivos de la anterior y aplica la nueva.
La base es portátil; la higiene mínima no se negocia
Dejar la base agnóstica fue deliberado. Un StorageClass, node pools con taints o un runtimeClassName en base/ rompen el quickstart en kind y estorban en cualquier proveedor. El punto medio: la base lleva solo lo que funciona igual en local y en GKE, y los ajustes del clúster viven en manifests/local/, un overlay estático con los parches comentados. kubectl apply -k manifests/local renderiza exactamente la base hasta que descomentes algo.
Ojo con el ciclo de vida: volver a aplicar local reconcilia la base, así que cualquier kubectl patch a mano —subir las réplicas del pool, cambiar IDLE_TIMEOUT— se pierde. Si el ajuste es del clúster, va en un parche del overlay. Los parches vienen en JSON 6902, para un campo puntual de un CR como storageClassName, o en strategic merge, para campos estándar como el env del gateway. Ambos comparten la misma trampa: si un target no calza con ningún objeto, Kustomize lo ignora sin avisar. Renderiza con kubectl kustomize manifests/local antes de creer que aplicaste un cambio.
Lo que sí vive en la base es lo que no se negocia:
automountServiceAccountToken: false. El pod del tenant no habla con la API. El gateway tiene pods/log sobre todos los pods del namespace, y esos logs contienen el launch token de cada instancia de DSH: montar el token del ServiceAccount en un sandbox es repartir las sesiones de los demás.- Contenedor hardened: UID/GID
1000, runAsNonRoot, allowPrivilegeEscalation: false, capabilities.drop: ["ALL"] y seccompProfile: RuntimeDefault. fsGroupChangePolicy: OnRootMismatch, que retomo cuando hablemos de reanudar.dnsConfig con ndots: "2" y single-request-reopen. Lo primero evita que un nombre con dos o más puntos pase primero por los sufijos de búsqueda. Lo segundo serializa las consultas A y AAAA que glibc manda en paralelo por el mismo socket UDP: si una respuesta se pierde, la primera resolución de un proceso nuevo se come los 5 s de timeout del resolver, justo el presupuesto del preflight de GitHub que DSH usa al instalar un plugin (githubConnectionTimeoutMs = 5000). En el repo quedó como ~5 s a ~0,1 s.
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxTemplate
metadata:
name: dsh-web
namespace: dsh-demo
spec:
envVarsInjectionPolicy: Disallowed
volumeClaimTemplatesPolicy: Disallowed
networkPolicyManagement: Unmanaged
service: true
podTemplate:
spec:
automountServiceAccountToken: false
dnsConfig:
options:
- name: ndots
value: "2"
- name: single-request-reopen
securityContext:
runAsNonRoot: true
runAsUser: 1000
runAsGroup: 1000
fsGroup: 1000
fsGroupChangePolicy: OnRootMismatch
# ... contenedor, probes y volumeClaimTemplates, recortados acá
Las dos políticas Disallowed convierten un error silencioso en un rechazo explícito: un claim que traiga spec.env o volumeClaimTemplates se rechaza (EnvVarsInjectionRejected) en vez de arrancar en frío. La única personalización compatible con el warm pool es etiquetar el pod con additionalPodMetadata, bajo el prefijo sandbox.users.io. Y networkPolicyManagement: Unmanaged significa eso: el controlador no genera políticas, así que sin la tuya el sandbox queda sin restricciones de red. Si pasas a Managed, define spec.networkPolicy o el gateway se queda afuera.
El otro detalle que muerde en cada actualización: cada Sandbox guarda una instantánea de su podTemplate. Parchar el template no toca los sandboxes ya creados ni los repuestos del pool (OnReplenish). Para actualizarlos hay que borrar los repuestos y suspender o recrear cada sandbox reclamado, lo que desconecta a usuarios activos: ventana de mantenimiento, no un kubectl de pasada.
Warm pools: registrarse es cambiar una etiqueta
Todo el trabajo caro —pull de imagen, PVC, arranque de DSH— ocurre antes de que exista el usuario. Un SandboxWarmPool con dos réplicas mantiene repuestos listos, cada uno con su PVC enlazado y DSH escuchando en 3080. El registro es un SandboxClaim de diez líneas que reetiqueta un sandbox disponible: el pod recibe sandbox.users.io/dsh-user, pierde agents.x-k8s.io/warm-pool-sandbox y el pool repone un repuesto para mantener la cuota.
| Recurso o campo |
Rol en la plataforma |
SandboxTemplate + volumeClaimTemplates |
Pods DSH idénticos, con el estado del usuario en un PVC de 5 Gi |
SandboxWarmPool |
Paga el aprovisionamiento antes de que exista el usuario |
SandboxClaim + warmPoolRef |
Asigna un pod reetiquetándolo; Ready en ~2 s |
envVarsInjectionPolicy / volumeClaimTemplatesPolicy |
Rechazan los claims que intenten saltarse el warm pool |
service: true |
DNS estable por sandbox (status.serviceFQDN) para enrutar |
spec.operatingMode |
Al suspender, borra solo el pod; PVC y Service sobreviven |
| Borrado en cascada |
Eliminar el claim borra el sandbox y su PVC |
# desde examples/dsh-agents-as-a-service/
. ../../versions.env
kubectl apply -f "https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yaml"
kubectl -n agent-sandbox-system rollout status deployment --timeout=180s
kubectl apply -f manifests/base/00-prereqs.yaml
kubectl -n dsh-demo create secret generic dsh-provider-keys \
--from-literal=DEEPSEEK_API_KEY="sk-..." --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -f manifests/base/10-sandboxtemplate.yaml -f manifests/base/20-sandboxwarmpool.yaml
# "registro": un claim, listo en ~2 s si hay repuesto
kubectl apply -f manifests/base/30-claim-alice.yaml
kubectl -n dsh-demo wait sandboxclaim dsh-alice --for=condition=Ready --timeout=60s
Tres cosas que conviene tener claras desde el día uno:
- Nombres. El sandbox adoptado conserva el nombre aleatorio que le asignó el pool. La plataforma resuelve usuario a sandbox leyendo
claim.status.sandbox.name, nunca asumiendo el nombre del claim. - Rotación de claves. Las claves entran por
envFrom y quedan fijadas al crear el pod: rotar el Secret obliga a borrar los repuestos y recrear los pods reclamados. Y una clave guardada en el almacén de credenciales de DSH gana sobre la variable de entorno, así que a veces recreas todo y sigue la vieja. - Claves compartidas.
dsh-provider-keys es obligatorio; dsh-provider-keys-extra es opcional (optional: true) para OpenRouter, Gemini, NVIDIA y compañía. En un warm pool no hay ventana previa al usuario donde inyectar claves individuales, así que todos los tenants comparten las mismas. Es una decisión de demo, no de producción.
Suspender y reanudar: el pod muere, los datos sobreviven
Suspender es un parche de un campo. El controlador elimina solo el pod; el PVC y el Service sobreviven. Al reanudar levanta un pod nuevo desde el podTemplate vigente y vuelve a montar el mismo volumen.
SB=$(kubectl -n dsh-demo get sandboxclaim dsh-alice -o jsonpath='{.status.sandbox.name}')
kubectl -n dsh-demo patch sandbox "$SB" --type merge -p '{"spec":{"operatingMode":"Suspended"}}'
kubectl -n dsh-demo patch sandbox "$SB" --type merge -p '{"spec":{"operatingMode":"Running"}}'
kubectl -n dsh-demo wait sandbox "$SB" --for=condition=Ready --timeout=180s
El punto crítico son los permisos en disco. DSH crea .credentials.yaml con 0600 y no arranca si el archivo quedó legible por grupo u otros. La política por defecto de kubelet (Always) hace un OR recursivo de 0660 sobre cada archivo al montar el volumen, así que un sandbox reanudado vuelve con 0660 y entra en CrashLoopBackOff antes de que el gateway alcance a enrutar nada. fsGroupChangePolicy: OnRootMismatch salta ese recorrido cuando la raíz del volumen ya tiene el dueño correcto. El log lo dice sin ambigüedad: is readable beyond its owner (mode 660).
Si tienes sandboxes creados antes de este ajuste, la migración no es un chmod -R: suspende el sandbox, monta su PVC en un pod auxiliar, corre chmod 600 sobre .credentials.yaml (no recursivo), parcha el podTemplate y reanuda.
Y revisa la reclaimPolicy de tu StorageClass. Con Retain, cada cuenta eliminada deja un PV en Released y su volumen en Longhorn. scripts/cluster-drift.sh los lista como warning; la limpieza va en el flujo de baja de usuarios.
El gateway: una réplica por diseño
El gateway es una app ASGI en Starlette que escucha en 8080 y convierte estos manifiestos en algo que una persona puede usar desde el navegador. Al registrarse, un usuario crea el claim, espera a que pase a Ready y recibe un token del que solo se guarda el hash SHA-256 como anotación (aaas.example.com/token-sha256), junto con una sesión opaca: una cookie HttpOnly, SameSite=Lax y Path=/ que transporta un id de servidor, nunca el token. Expira a los siete días (COOKIE_MAX_AGE).
El navegador jamás ve el launch token. El gateway lo saca de los logs del pod (DSH_LOG_TAIL_LINES, 2000 líneas por defecto), completa el handshake ?token= por detrás y guarda la cookie dsh-auth-* en memoria, cacheada por usuario, UID del pod y Host. Esa lectura de logs es el punto más frágil y no lo voy a disfrazar: si los logs rotan demasiado rápido o DSH cambia el mensaje de arranque, el handshake no encuentra el token y responde 503 con Retry-After: 10. DSH sigue en developer preview, así que ese formato puede cambiar.
Los probes están separados a propósito. En el sandbox apuntan a /favicon.svg, porque / responde 401 sin token y un probe ahí manda el pod a CrashLoopBackOff con una puntualidad admirable. El startupProbe da 120 s para que un arranque en frío no muera a mitad de camino. En el gateway, /healthz es liveness puro y no toca la API, mientras /readyz hace una lectura acotada al clúster. Si se cae el egress o se revoca un verbo de RBAC, el proceso sigue vivo, los usuarios reciben 500 y /readyz es el que saca el pod de los endpoints.
Todo lo que está bajo /u/{user}/ se proxea al sandbox: assets, API, SSE y WebSocket. El enrutamiento por prefijo funciona sin DNS wildcard porque DSH trabaja con rutas relativas. El sweeper suspende solo cuando DSH confirma que no queda ningún agente corriendo (POST /api/session/list); si ese probe falla, no suspende. Cerrar la pestaña no mata un agente a mitad de turno, y los claims aplicados a mano —sin aaas.example.com/managed-by— no se tocan nunca. El manifiesto base deja IDLE_TIMEOUT=360 y WAKE_TIMEOUT=240; el e2e los baja a 60 y 120.
replicas: 1 no es deuda técnica pendiente: es el contrato. Los relojes de inactividad, los contadores en vuelo, la caché del handshake, la tabla de sesiones y los buckets de rate limiting viven en memoria. Dos réplicas suspenderían dos veces, perderían el wake y mandarían la sesión a la réplica equivocada. El RBAC mínimo: get/list/create/patch/delete sobre sandboxclaims (el patch está reservado para compatibilidad), get/list/patch sobre sandboxes —el único write de CRD, suspender y reanudar—, get/list sobre pods y get sobre pods/log.
Los controles de abuso son por proceso: 30 intentos de autenticación cada 60 s (con 429 y Retry-After antes de leer el cuerpo), código de invitación opcional, 32 peticiones concurrentes por usuario, tramas WebSocket de 16 MiB y cuerpos HTTP de 32 MB. Antes de proxear, el gateway borra Forwarded, todo X-Forwarded-*, todo X-Auth-Request-* y X-Real-IP; las mutaciones con cookie y los upgrades de WebSocket exigen que Origin calce con Host, y el Set-Cookie del upstream no se reenvía. También se niega a arrancar con COOKIE_SECURE=false salvo que ALLOW_INSECURE_COOKIES=1 lo autorice.
kubectl -n dsh-demo port-forward svc/dsh-gateway 18080:8080 &
JAR=$(mktemp)
curl -s -i -c "$JAR" -H 'Origin: http://localhost:18080' \
-d 'user=bob' http://localhost:18080/users # registro
curl -s -b "$JAR" http://localhost:18080/u/bob/ | head -5 # UI proxeada
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:18080/u/bob/ # 401
La contrapartida es la de siempre: las sesiones viven en memoria. Reiniciar el gateway cierra la sesión de todos; los tokens sobreviven, las sesiones no.
Exposición: elige una puerta y cierra la otra
| Overlay |
Punto de entrada |
Autenticación |
TLS |
exposure/ingress/ |
Ingress de Traefik en / |
Registro y cookies opacas del propio gateway |
Opcional, recomendado en el Ingress (dsh-example-tls de ejemplo) |
exposure/gateway-api-sso/ |
Gateway + HTTPRoute |
GitHub OAuth vía oauth2-proxy en 4180 |
Obligatorio en el listener |
El overlay de Ingress define el host en un solo archivo y lo copia al SAN del certificado TLS y a DSH_TRUSTED_HOSTS del template; sin eso, DSH bloquea /api al comparar Host contra su lista blanca. No le pongas middlewares de buffering ni compresión: rompen SSE y los upgrades de WebSocket bajo /u/<user>/**.
El de SSO antepone oauth2-proxy (con --github-org como criterio de autorización) y manda todo el HTTPS a oauth2-proxy:4180. Tras el login, el proxy reenvía a dsh-gateway:8080 con X-Forwarded-User, y el overlay configura AUTH_PROXY_HEADER, COOKIE_SECURE y TRUSTED_PROXY_HOPS=2 para que el rate limiter cuente los dos saltos en vez de meter a todos en el mismo bucket.
Acá está la frontera de confianza, y conviene leerla dos veces: cualquiera que alcance dsh-gateway:8080 directo puede mandar X-Forwarded-User: <víctima>. Por eso las tres NetworkPolicy de la variante —dsh-gateway-ingress, oauth2-proxy-ingress y oauth2-proxy-egress— no son adornos: el gateway solo acepta tráfico de oauth2-proxy, el proxy solo del namespace de tu implementación de Gateway, y su salida queda en DNS, el gateway y HTTPS público, con rangos privados, CGNAT, link-local y el endpoint de metadatos bloqueados.
Hay un detalle que muerde justo después de activar TLS: DSH compara Host bajo el esquema del Origin, así que una página HTTPS manda Origin: https://<host> y la petición tiene que llegar a DSH con X-Forwarded-Proto: https. Un gateway viejo que reenvía el esquema de su conexión al pod hace que todas las llamadas a /api devuelvan 403. cluster-drift.sh reporta ese par de condiciones a la vez. Y preflight-sso.sh falla si el namespaceSelector de oauth2-proxy-ingress no calza con ningún pod real: la referencia es kube-system, donde viven Traefik en k3s y en kind, y si tu Gateway corre en otro namespace el síntoma es un 502 en todas las rutas, /healthz incluido. El script también valida el cookie-secret (16, 24 o 32 bytes), los placeholders sin reemplazar y el RBAC para patch sobre sandboxes.
Un matiz que el README todavía lista como riesgo abierto: la cabecera solo se honra para un claim que ese gateway emitió (el que lleva aaas.example.com/token-sha256); uno aplicado a mano se rechaza. Eso acota el daño, no reemplaza la política de red: la cabecera no está firmada y, sin NetworkPolicy, cualquier claim emitido por el gateway sigue alcanzable desde donde sea.
Hardening: la demo no es el producto
Los manifiestos tal cual son una demo, y la documentación no lo esconde. Si esto va a producción, este es el orden por impacto:
- gVisor.
runtimeClassName: gvisor en el SandboxTemplate y en el gateway. Editar el template no toca los sandboxes activos: hay que parchar cada uno, suspenderlo y reanudarlo, y borrar los repuestos para que el pool los reponga. kubectl port-forward deja de funcionar con gVisor, así que el camino es el gateway. - NetworkPolicy de los sandboxes. El componente
manifests/optional/network-policy selecciona pods por agents.x-k8s.io/sandbox-name-hash, así que cubre también los repuestos y los sandboxes existentes sin recrearlos. Entrada solo desde app: dsh-gateway al 3080; salida a DNS, NodeLocal DNS y HTTPS público. Requiere un CNI que aplique NetworkPolicy, y los probes del kubelet pueden necesitar una regla aparte. - Egress del gateway. No viene por defecto porque la IP del API server cambia en cada clúster. CNIs como
kube-router evalúan el egress después del DNAT: permitir el ClusterIP de kubernetes no basta si el endpoint real es otra IP, y el fallo es silencioso —/healthz responde 200 y todas las rutas devuelven 500—. cluster-drift.sh compara la política contra el endpoint real. - Node pools dedicados.
nodeSelector y tolerations para dejar los sandboxes en un pool aparte, idealmente con GKE Sandbox, lejos del control plane. failedPodPolicy: Recreate. Desde agent-sandbox v1.0.8, reemplaza un pod desalojado en vez de dejar el sandbox estacionado en Finished=True devolviéndole errores al usuario. Con restartPolicy: OnFailure, el caso realista es el desalojo del nodo, no un contenedor que muere.- Deriva.
cluster-drift.sh compara el clúster con lo declarado sin modificar nada; preflight-sso.sh revisa la variante SSO antes de abrir tráfico real.
Y la advertencia más incómoda: el template fija DSH_PERMISSION_MODE=danger-full-access. No es un descuido. El sandbox interno de comandos de DSH depende de bubblewrap o Landlock; dentro de este pod, bubblewrap viene sin setuid y necesita un user namespace sin privilegios que el perfil seccomp y las capabilities descartadas no conceden, y no hay runner de Landlock disponible. El ejecutor no encuentra backend y todo comando muere con SANDBOX_UNAVAILABLE. La decisión fue mover la frontera al pod completo: un pod por usuario, non-root, cero capabilities, seccomp RuntimeDefault, PVC y Service propios.
La consecuencia práctica es incómoda: un comando del agente puede leer su propio .credentials.yaml y escribir en cualquier parte del contenedor, y como las claves de proveedor son compartidas, esas credenciales valen para todos los tenants. En producción eso exige gVisor, credenciales por usuario o un proxy de egress. Donde el backend de DSH funcione, vuelve a workspace-write o read-only y recrea el pod, porque el valor se fija al crear el contenedor.
El resto es criterio de plataforma: warm pools para no pagar el arranque en cada registro, operatingMode como perilla de costo, autenticación que falla hacia el lado seguro, un gateway que se niega a arrancar con configuraciones inseguras en vez de esconder la advertencia en la letra chica, y una separación limpia entre lo portátil y lo que es de tu clúster. Las limitaciones están claras: sesiones en memoria, token sacado de los logs, autorización reducida a una organización de GitHub y claves compartidas. Tómalo como base, aplica el hardening que te toca y deja que los agentes duerman cuando sus usuarios descansan. La factura lo nota.
Referencias