Kelos y kubernetes: agentes codigo en homelab (2026)

TL;DR (resumen ejecutivo)

Kelos (kelos-dev/kelos) es un operador Kubernetes en Go (Apache-2.0) que modela agentes de código autónomos como recursos declarativos: Tasks, Workspaces, AgentConfigs y TaskSpawners. Un flujo típico de kelos kubernetes agentes codigo parte de un evento (issue, PR, cron), Kelos crea una task kubernetes efímera, inyecta credenciales y captura salidas (rama, SHA, URL de PR). Sirve cuando quieres GitOps de flujos de agente; no sustituye revisión humana ni políticas de merge. Esta guía enlaza instalación oficial, riesgos y homelab con kind.

Tiempo de lectura: unos 42 minutos | Nivel: avanzado (Kubernetes + LLM APIs) | Actualización: abril 2026

—

Tabla de contenidos

1. Introducción
2. Qué resuelve kelos kubernetes agentes codigo
3. Primitivas: task kubernetes y TaskSpawners
4. Requisitos de clúster y toolchain
5. Instalación y primer contacto
6. Seguridad: RBAC, secretos y red
7. GitOps y ci cd ia con manifiestos Kelos
8. Arquitectura del operador y reconciliación
9. Ciclo de vida de una task kubernetes
10. kind, RAM y límites prácticos en homelab
11. Política de PRs y revisión humana
12. Matriz extendida frente a alternativas
13. Runbook de actualización de Kelos
14. Cuándo no conviene Kelos
15. Comparativas
16. Troubleshooting: kelos kubernetes agentes codigo
17. Descargar ejemplos en GitHub
18. Observabilidad y SLO para agentes
19. Multi-tenant y límites organizativos
20. Enlaces relacionados
21. Preguntas frecuentes
22. Conclusión

—

Introducción

Los agentes en terminal (Claude Code, Codex, Gemini, OpenCode, Cursor…) funcionan bien interactivos; el salto es convertirlos en trabajadores que reaccionan a Issues sin que nadie pulse Enter. Ahí entra Kelos: kubernetes como plano de control, YAML versionado y operador que orquesta ciclos de vida. En homelab te permite experimentar con Kelos y agentes codigo kubernetes sin montar un Rube Goldberg de CronJobs bash. El riesgo es autonomía mal acotada: sin etiquetas de pausa (kelos/needs-input en los ejemplos públicos) y sin maxConcurrency, puedes saturar proveedores o generar PRs basura. Este artículo no sustituye la documentación oficial del repositorio kelos-dev/kelos; sirve como mapa mental y checklist para que tu primer clúster no acabe en incidente de facturación o en spam de pull requests.

—

Qué resuelve kelos kubernetes agentes codigo

Un stack Kelos para agentes codigo kubernetes concentra:

• Disparadores declarativos (GitHub Issues/PRs, cron) vía TaskSpawner.
• Unidades de trabajo (Task) con aislamiento en Pods efímeros.
• Contexto persistente o efímero (Workspace) para clones git.
• Perfiles de agente reutilizables (AgentConfig) con instrucciones y MCP.

Es distinto de lanzar un Job genérico: Kelos conoce handoffs, plantillas de prompt y metadatos de salida orientados a PRs. Para orquestación genérica de agentes también existe Dapr Agents en Kubernetes, útil como contraste de primitives.

—

Primitivas: task kubernetes y TaskSpawners

Task

La task kubernetes encapsula una corrida de agente: imagen del runner, modelo, prompt y límites. Observa kubectl describe task -n kelos-lab cuando falle: eventos de scheduling suelen delatar quotas o imagePullBackOff.

TaskSpawner

Reacciona a fuentes externas y crea Tasks automáticamente. El README muestra pollInterval, maxConcurrency y filtros por labels de GitHub; son tu primer muro contra bucles infinitos.

Workspace y AgentConfig

Separan dónde trabaja el agente del cómo se comporta. Versiona AgentConfig en git y trata cada cambio como cambio de política de producto.

—

Requisitos de clúster y toolchain

• Kubernetes 1.28+ (requisito del proyecto).
• kubectl, helm si usas chart OCI en GHCR.
• kind o k3d para laboratorio; en el repo de ejemplos dejamos scripts/kind-bootstrap.sh (ver sección GitHub al final).
• Tokens de LLM y PAT de GitHub con alcance mínimo.

kind version
kubectl version --client

—

Instalación y primer contacto

El repositorio documenta tres caminos: curl …/hack/install.sh | bash (revísalo antes), go install github.com/kelos-dev/kelos/cmd/kelos@latest, y Helm con artefacto OCI. Elige uno y fija versión en tu runbook.

# Tras instalar operador/CRDs según docs vigentes
kubectl get crd | grep kelos || true
kubectl get pods -A | head

No copies comandos Helm sin leer la sección actual del README: los valores cambian entre releases.

—

Seguridad: RBAC, secretos y red

Namespace dedicado (kelos-lab en nuestro ejemplo), NetworkPolicy si tu CNI lo permite, y ResourceQuota para CPU/mem. Los agentes codigo kubernetes siguen siendo código arbitrario: limita egress salvo que necesites APIs externas explícitas. Rota PAT y claves LLM; nunca las commitees en el mismo repo que los manifiestos si es público.

Integra mentalidad de MCP cuando conectes herramientas: cada socket expuesto al Pod es superficie nueva.

—

GitOps y ci cd ia con manifiestos Kelos

Tratar Kelos como infra implica ci cd ia serio: validación kubectl apply --dry-run=server, políticas OPA/Gatekeeper opcionales, y MRs que muestren diff de TaskSpawner antes de tocar producción. Flux/Argo pueden reconciliar el mismo YAML que revisas en PR; así conectas el operador Kelos con la cultura GitOps que ya uses para apps.

# Ejemplo de validación server-side antes de merge (ajusta rutas a tu repo)
kubectl apply --dry-run=server -f platform/kelos/
kubeconform -strict -summary platform/kelos/

Documenta en el mismo MR qué versión de Kelos probaste localmente (helm list -n kelos-lab o equivalente). Esa correlación evita el clásico “en mi kind funcionaba” cuando el chart de producción arrastra valores distintos.

—

Arquitectura del operador y reconciliación

Kelos encaja en el patrón Kubernetes operator: controladores observan objetos kelos.dev y crean o actualizan Pods, Secrets montados y Jobs auxiliares según el estado deseado. Para ti como operador del stack Kelos en clúster, lo relevante no es memorizar cada reconciler interno, sino entender qué recursos son fuente de verdad (tus YAML en git) y cuáles son efímeros (Pods de Tasks que desaparecen al terminar). Cuando algo falla, la cadena suele ser: TaskSpawner detecta evento → se materializa Task → el Workspace prepara checkout → el contenedor del agente ejecuta herramientas y abre PR. Si rompes cualquier eslabón (PAT revocado, imagen incorrecta, cuota de CPU), el síntoma aparece en Events del recurso equivocado; por eso conviene un dashboard mínimo con kubectl get programado o exportado a tu stack de observabilidad.

La disciplina de task kubernetes como unidad mínima te obliga a pensar en idempotencia: dos Tasks que intentan el mismo cambio sobre la misma rama pueden chocar. Diseña nombres de rama o prefijos por issue, y usa etiquetas de GitHub para serializar trabajo humano vs automático. Esa convención es más barata que reescribir lógica en el operador.

—

Ciclo de vida de una task kubernetes

Una task kubernetes en Kelos no es un Deployment estable: nace, corre y muere. El flujo típico homelab es: (1) el TaskSpawner evalúa filtros y decide crear recurso; (2) el controlador programa Pod con la imagen de agente declarada; (3) se montan Secret con tokens y variables; (4) el agente clona o reutiliza Workspace; (5) se registran salidas (logs, metadatos de PR); (6) el recurso finaliza o queda en estado de error explícito. En cada paso puedes instrumentar: kubectl describe task para eventos, kubectl logs para razonamiento del modelo (ojo con PII), y métricas del proveedor LLM para coste. Si entrenas al equipo en ese circuito, bajan las consultas vagas de “Kelos va raro” y suben los informes con contexto reproducible.

Para agentes codigo kubernetes es tentador saltarse el paso (5) y mirar solo el PR en GitHub; añade siempre el enlace al Task en tu plantilla de revisión interna. Así el revisor humano puede correlacionar diff con prompt y versión de AgentConfig.

—

kind, RAM y límites prácticos en homelab

kind es la vía rápida para validar CRDs y un par de Tasks de humo, pero el nodo Docker compite con el IDE, el navegador y los modelos locales. Con menos de 12–16 GB de RAM libre verás throttling y Evicted en Pods de agente que descarguen modelos o dependencias pesadas. Ajusta extraPortMappings solo si necesitas depurar servicios desde el host; cada apertura es superficie. Si iteras imágenes privadas, monta un registry local o imagePullSecrets para no depender de rate limits anónimos de Docker Hub. El script kind-bootstrap.sh del repo de ejemplos es un punto de partida; adáptalo a tu CPU y a la política de red corporativa antes de copiarlo a producción.

Cuando pases de kind a un clúster “real” pequeño (k3s en metal, GKE autopilot de pruebas, etc.), revisa de nuevo ci cd ia: el mismo YAML puede comportarse distinto por admission webhooks o políticas de PSP/PSS que no existían en tu portátil.

—

Política de PRs y revisión humana

Kelos en producción brilla cuando las reglas de merge son estrictas: ramas protegidas, revisores obligatorios, tests en GitHub Actions que no dependan del agente, y convención de que los PRs automáticos llevan prefijo en título ([kelos] o similar). Si permites merge sin revisión porque “es solo docs”, un prompt malicioso o un issue envenenado puede colar cambios sutiles. Combina etiquetas de exclusión en TaskSpawner con CODEOWNERS por paths sensibles (/infra, /security). La revisión humana no es derroche: es el último control cuando el modelo alucina una dependencia o toca secretos por accidente.

Documenta también qué hace el equipo si Kelos se queda en bucle: quién escala el Deployment del controlador a cero, quién rota PAT, y en qué canal de incidentes se avisa. Un runbook de una página evita decisiones a las tres de la mañana.

—

Matriz extendida frente a alternativas

Más allá de la tabla corta más abajo, conviene situar Kelos frente a patrones que ya uses. GitHub Actions + scripts gana en simplicidad y pierde en declarabilidad de recursos de agente; Argo Workflows gana en DAG genérico y pierde en especialización para handoffs de código; Dapr Agents (ver Dapr Agents Kubernetes) aporta primitives de mensajería durable distintas a las CRDs kelos.dev. Si tu problema es “quiero un job que llame a la API de OpenAI”, no necesitas Kelos; si tu problema es “quiero que Issues etiquetados disparen agentes versionados en git con límites de concurrencia”, Kelos encaja mejor.

La columna de agentes codigo kubernetes no es religión: puedes convivir con varias herramientas si los namespaces y los triggers están desacoplados.

—

Runbook de actualización de Kelos

Antes de subir chart o manifiestos: lee el changelog del tag, exporta el estado actual (kubectl get tasks,workspaces,agentconfigs,taskspawners -A -o yaml > backup-kelos.yaml), y prueba en kind la misma secuencia de upgrade. Si el proyecto cambia apiVersion o nombres de campos, tus TaskSpawner antiguos pueden quedar no reconciliables hasta editarlos.

# Comprueba versión instalada vs CRDs presentes
kubectl get crd | grep kelos
helm history kelos -n kelos-lab 2>/dev/null || true

Tras el upgrade, ejecuta una Task de humo contra un repo canario antes de reactivar TaskSpawners productivos.

—

Cuándo no conviene Kelos

Evita Kelos si no tienes aún RBAC claro, si tu organización prohíbe PAT con acceso a repos sensibles, o si el coste marginal de APIs LLM no está presupuestado. Tampoco es buena idea si tu flujo real es “un humano escribe el 100 % del código y solo quieres autocompletado en IDE”: ahí los operadores añaden complejidad sin retorno. task kubernetes tiene sentido cuando el volumen de issues o el ritmo de parches justifica automatizar; de lo contrario, un bot de comentarios con plantillas y un par de Actions suelen bastar.

—

Comparativas

—

Troubleshooting: kelos kubernetes agentes codigo

kubectl get tasks,workspaces,agentconfigs,taskspawners -A
kubectl logs -n kelos-lab deploy/kelos-controller-manager 2>/dev/null || true

Errores típicos: CRD no instalada, versión de API kelos.dev/v1alpha1 incompatible, imágenes de agente privadas sin imagePullSecrets, o maxConcurrency demasiado alto para tu cuota de API.

Tasks que no arrancan o quedan en Pending

Revisa kubectl describe task -n kelos-lab buscando FailedScheduling, Insufficient cpu o pod has unbound immediate PersistentVolumeClaims. En homelab suele bastar subir límites del nodo kind o reducir requests en el manifiesto del agente. Si el mensaje apunta a ImagePullBackOff, verifica digest y credenciales del registry antes de culpar al operador.

Respuestas 401/403 del proveedor LLM

Rotación de clave, scope incorrecto o reloj desincronizado en el nodo (JWT caducados). Comprueba que el Secret montado coincide con el entorno (clave de staging vs producción). En despliegues Kelos multi-equipo, centraliza secretos con ExternalSecrets o Vault y evita duplicar el mismo token en diez namespaces.

PRs duplicados o ramas conflictivas

Suele ser TaskSpawner demasiado agresivo o dos disparadores distintos sobre el mismo label. Añade excludeLabels, baja pollInterval y acuerda prefijos de rama por issue. Los revisores humanos agradecerán un solo PR coherente frente a tres mitades.

Ruido en logs y coste inesperado

Activa presupuestos en el proveedor y alertas por tokens/día. Cruza con la sección de observabilidad: sin métricas mínimas, el troubleshooting se convierte en adivinanza sobre qué task kubernetes disparó el pico.

—

Descargar ejemplos en GitHub

Material mínimo (kind-bootstrap.sh, namespace-lab.yaml, fragmento de TaskSpawner) en el repositorio de ejemplos Kelos homelab.

—

Observabilidad y SLO para agentes

Define qué significa “healthy” para tu instalación Kelos (agentes de código en el clúster): latencia media de creación de Task, ratio de Tasks completadas vs fallidas, tokens consumidos por hora. Exporta métricas del controlador si el chart las expone; si no, centraliza al menos logs en Loki y alertas por palabras clave (429, 401, ImagePullBackOff). Cruza lecturas con MLOps local para no tratar los agentes como caja negra fuera del resto de tu plataforma.

—

Multi-tenant y límites organizativos

Si varios equipos comparten clúster, aísla Kelos por namespace y por cuenta de GitHub/PAT distintas. Evita que dos TaskSpawners disparen contra el mismo repo sin coordinación: los labels de issue pueden colisionar y generar PRs duplicados. Documenta propietarios (CODEOWNERS) y reglas de merge que exijan revisión humana cuando el autor del PR sea un bot de Kelos.

—

Enlaces relacionados

• Dapr Agents Kubernetes
• MCP: Model Context Protocol
• OpenAI Agents SDK
• A2A Protocol + MCP
• Flowise RAG
• LangChain vs LlamaIndex
• MLOps local
• Tailscale homelab
• WireGuard VPN self-hosted
• Open WebUI con Ollama-plugins/)
• LocalAI OpenAI-compatible

—

Preguntas frecuentes

¿Kelos requiere Kubernetes obligatorio?

Sí. El proyecto se basa en CRDs y un operador; no hay modo soportado “solo Docker”. Para aprender, usa kind en tu portátil o un clúster k3s dedicado.

¿Qué licencia usa el proyecto Kelos?

Apache-2.0 según el repositorio oficial; confirma el fichero LICENSE en el tag que instales. Eso no licencia los modelos LLM ni el contenido de tus repos.

¿Qué agentes soporta Kelos out of the box?

El README lista Claude Code, OpenAI Codex, Google Gemini, OpenCode y Cursor, además de imágenes personalizadas siguiendo la interfaz documentada en docs/agent-image-interface.md.

¿Cómo limito coste de APIs en un homelab?

Combina maxConcurrency en TaskSpawners, modelos más baratos en entornos de prueba, presupuestos en el proveedor y horarios de Cron más laxos. Monitoriza tokens por Task.

¿Puedo usar Kelos sin GitHub?

Los ejemplos públicos giran en torno a GitHub Issues/PRs; otros SCM requerirían integraciones o TaskSpawners personalizados no cubiertos en esta guía. Consulta docs/integration.md en el upstream.

¿Qué es una task kubernetes en Kelos?

Un recurso Task representa una ejecución concreta de agente: imagen, prompt, límites y resultados. Es la pieza que observas con kubectl get/describe cuando depuras.

¿Cómo pauso un flujo autónomo peligroso?

Aplica el patrón de labels excludeLabels del README (p.ej. kelos/needs-input), escala a cero el TaskSpawner temporalmente, o revoca el PAT hasta entender el incidente.

¿Helm o script de instalación?

Helm suele encajar mejor en GitOps; el script es útil para prototipos rápidos. Elige uno y documenta valores (values.yaml) en git.

¿kind es suficiente para aprender?

Sí para CRDs y flujos básicos; no para cargas GPU pesadas ni HA real. Aumenta RAM del nodo Docker si ves eviction.

¿Cómo conecto MCP de forma segura?

Monta MCP en red restringida, usa mTLS donde sea posible y limita herramientas expuestas al mínimo viable; revisa la guía de MCP.

¿Kelos sustituye a mi pipeline CI/CD clásico?

Complementa o se superpone: puedes seguir usando Actions para tests y Kelos para triage autónomo. Evita dos sistemas que abran PRs por la misma issue sin reglas claras.

¿Dónde veo ejemplos YAML oficiales?

Carpeta examples/ y self-development/ en el repositorio kelos-dev/kelos; copia solo lo necesario y entiende cada campo antes de aplicar.

¿Cómo evito que un TaskSpawner cree miles de Tasks?

Filtros estrictos de labels, maxConcurrency bajo, pollInterval razonable y cuotas de namespace. Prueba en repo canario antes del monorepo real.

¿Qué versión mínima de Kubernetes necesito?

El README indica 1.28+; versiones inferiores pueden no soportar APIs requeridas por el operador.

—

Conclusión

kelos kubernetes agentes codigo es una apuesta fuerte: cambias flexibilidad ad-hoc por declarative harness en el plano de datos de tu clúster. Úsalo cuando tu equipo ya respire GitOps y quiera tratar agentes como cargas más, no como hacks en un VPS. Si aún no dominas RBAC y admisión, invierte primero en fundamentos; Kelos amplifica tanto buenas como malas prácticas. Mantén siempre un repo canario y métricas mínimas antes de soltar TaskSpawners contra producción.