Construí un Agente IA Cluster-Aware con Kubernetes, Argo CD y GitOps

Introducción

¿Necesitás un agente de IA que entienda tu cluster de Kubernetes sin salir de tu red? Este tutorial te guía para montar un sistema autónomo donde el agente corre dentro del cluster, consulta el estado real de los recursos mediante la API de Kubernetes y responde usando un modelo local Mistral 7B, todo bajo un esquema GitOps estricto. No hay SaaS externo, no hay fuga de datos y cada permiso está explícitamente limitado a read-only.

El resultado es un asistente de DevOps que:

• Diagnostica fallos de pods con comandos exactos kubectl en la respuesta
• Se integra con tu pipeline de CI/CD existente usando GitHub Actions y Argo CD Image Updater
• Escalable: cada nueva capacidad se agrega con RBAC explícito y revisión manual

Qué es y para qué sirve

Un agente cluster-aware es una aplicación que combina:

1. Observabilidad: Lee el estado real del cluster (pods, eventos, logs) mediante la API de Kubernetes.
2. Razonamiento: Usa un modelo de lenguaje local (LLM) para interpretar esos datos y generar respuestas accionables.
3. GitOps estricto: El código, la configuración y las imágenes se actualizan siguiendo el flujo de GitOps, sin cambios directos al cluster.

Software y versiones exactas

• Kubernetes: v1.28 o superior (probado en v1.28.4)
• kubectl: v1.28.2
• Argo CD: v2.10.9
• Argo CD Image Updater: v0.14.0
• Ollama: v0.2.9 (para servir el modelo Mistral 7B)
• GitHub CLI: v2.47.0
• Docker: v25.0.3 (con buildx y QEMU para multi-arquitectura)
• Rust: v1.75.0 (para compilar el agente desde el código fuente)
• Python: v3.11 (para scripts de validación opcionales)

Permisos y accesos

• Un cluster de Kubernetes con permisos de cluster-admin para configurar RBAC
• Acceso a GitHub con permisos de write en un repositorio nuevo (o fork del repo de referencia)
• Cuenta de Docker Hub (o cualquier registry público/privado) con permisos de push/pull
• Acceso a un terminal Linux/macOS con Docker instalado y al menos 16 GB de RAM para descargar el modelo Mistral 7B

Guía paso a paso

Paso 1: Preparar el repositorio y clonar el proyecto

1. Crea un repositorio vacío en GitHub:

   gh repo create tu-usuario/local-k8s-ai-agent --public --clone
   cd local-k8s-ai-agent
   

1. Clona el proyecto de referencia como referencia:

   git remote add upstream https://github.com/MaryamTavakkoli/local-k8s-ai-agent.git
   git fetch upstream
   git checkout -b setup origin/main
   

1. Copia los archivos al repositorio local:

   cp -r upstream/* .
   

1. Edita .github/workflows/build-push.yml para apuntar a tu registry:

   env:
     REGISTRY: ghcr.io
     IMAGE_NAME: ${{ github.repository }}
   

Paso 2: Configurar el modelo local con Ollama

1. Instala Ollama en tu máquina local (o en un nodo del cluster con GPU):

   curl -fsSL https://ollama.com/install.sh | sh
   

1. Descarga el modelo Mistral 7B (requiere ~14 GB de RAM):

   ollama pull mistral
   

1. Verifica que Ollama esté corriendo:

   curl -s http://localhost:11434/api/tags | jq .
   

Paso 3: Crear el ServiceAccount y RBAC read-only

1. Crea un namespace para el agente:

   kubectl create ns ai-agent
   

1. Crea un ServiceAccount con permisos read-only:

   # manifests/rbac.yaml
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: ai-agent
     namespace: ai-agent
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: ai-agent-reader
   rules:
     - apiGroups: [""]
       resources: ["pods", "events", "pods/log"]
       verbs: ["get", "list"]
     - apiGroups: ["apps"]
       resources: ["deployments", "statefulsets"]
       verbs: ["get", "list"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: ai-agent-reader
   subjects:
     - kind: ServiceAccount
       name: ai-agent
       namespace: ai-agent
   roleRef:
     kind: ClusterRole
     name: ai-agent-reader
     apiGroup: rbac.authorization.k8s.io
   

1. Aplica la configuración:

   kubectl apply -f manifests/rbac.yaml
   

Paso 4: Configurar Argo CD e Image Updater

1. Instala Argo CD en el cluster:

   kubectl create namespace argocd
   kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.10.9/manifests/install.yaml
   

1. Espera a que Argo CD esté listo:

   kubectl wait -n argocd deploy/argocd-server --for=condition=available --timeout=300s
   

1. Instala Argo CD Image Updater:

   kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/v0.14.0/deploy/install.yaml
   

1. Configura el Image Updater para que escuche al registry:

   # manifests/argocd-image-updater-config.yaml
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: argocd-image-updater-config
     namespace: argocd
   data:
     registries.conf: |
       registries:
         - name: Docker Hub
           prefix: docker.io
           api_url: https://registry-1.docker.io
           credentials: secret:argocd/argocd-image-updater-secret
           default: true
   

1. Aplica la configuración:

   kubectl apply -f manifests/argocd-image-updater-config.yaml
   

Paso 5: Desplegar el agente con Argo CD

1. Crea una aplicación en Argo CD para el agente:

   argocd app create ai-agent \
     --repo https://github.com/tu-usuario/local-k8s-ai-agent \
     --path manifests \
     --dest-server https://kubernetes.default.svc \
     --dest-namespace ai-agent \
     --sync-policy automated \
     --self-heal
   

1. Crea un Custom Resource para Image Updater:

   # manifests/ai-agent-image-updater.yaml
   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
     name: ai-agent-image-updater
   spec:
     destination:
       namespace: ai-agent
       server: https://kubernetes.default.svc
     source:
       path: manifests
       repoURL: https://github.com/tu-usuario/local-k8s-ai-agent
       targetRevision: main
     syncPolicy:
       automated:
         prune: true
         selfHeal: true
   

1. Aplica el CR:

   kubectl apply -f manifests/ai-agent-image-updater.yaml
   

Paso 6: Configurar el prompt del modelo

Edita src/system_prompt.rs para personalizar el prompt del modelo:

pub const SYSTEM_PROMPT: &str = r#"
Eres un asistente de DevOps especializado en Kubernetes.
Ante un error o pregunta:
1. Explica el problema claramente
2. Proporciona los comandos exactos para diagnosticar o solucionar
3. Explica por qué la solución funciona

Responde en español rioplatense, de forma concisa y práctica.
"#;

Paso 7: Construir y subir la imagen con GitHub Actions

1. Haz un commit inicial:

   git add .
   git commit -m "Configuración inicial del agente"
   git push origin setup
   

1. Abre una Pull Request para que GitHub Actions construya la imagen:

   gh pr create --title "Setup inicial" --fill
   

1. Espera a que el workflow termine y verifica la imagen en el registry:

   docker pull ghcr.io/tu-usuario/local-k8s-ai-agent:$(git rev-parse --short HEAD)
   

Paso 8: Probar el agente

1. Obtén la URL del servicio del agente:

   kubectl get svc -n ai-agent
   

1. Envía una solicitud al agente:

   curl -X POST http://<SERVICE_IP>:8000/ask \
     -H "Content-Type: application/json" \
     -d '{"question": "¿Por qué mi pod api-7b8d está en ImagePullBackOff?", "namespace": "default"}'
   

{
  "answer": "Pod api-7b8d está en ImagePullBackOff porque no puede descargar la imagen de registry.local.\n\nEjecuta:\n

}

«`

Consideraciones y buenas prácticas

Limitaciones conocidas

• Recursos: Mistral 7B requiere al menos 16 GB de RAM. En clusters sin GPU, considera usar un modelo más pequeño como llama3:8b.
• Latencia: Cada solicitud al LLM agrega ~2-3 segundos de latencia. Usa caching de respuestas en el agente si necesitas escalabilidad horizontal.
• RBAC: El agente solo tiene permisos read-only. Si necesitás que ejecute comandos kubectl, agregá verbos create, delete, etc., pero siempre con revisión manual y en un namespace dedicado.

Alternativas

• Modelos: Si Mistral 7B no se adapta a tu workload, probá phi3:3.8b (requiere ~8 GB de RAM) o gemma:7b (más rápido pero menos preciso).
• CI/CD: Si no querés usar Argo CD Image Updater, podés reemplazarlo con Flux CD o renovar manualmente los manifests.

Seguridad

• No expongas el puerto del modelo: Ollama debe correr en un namespace separado con NetworkPolicy que lo aisle del resto del cluster.
• Rotación de tokens: Si usás registry privado, configura renovación automática de credenciales en Argo CD Image Updater.

Conclusión

Lograste un agente de IA que:

1. Corre dentro de tu cluster, sin exponer datos ni depender de proveedores externos.
2. Sigue GitOps estricto: cada cambio pasa por Git, Argo CD lo aplica y el Image Updater actualiza las imágenes automáticamente.
3. Tiene permisos estrictamente limitados a read-only, minimizando el riesgo de incidentes.

• Agrega más capacidades al RBAC (ej: permisos para leer ConfigMaps o Secrets) siguiendo el principio de least privilege.
• Implementá caching de respuestas para reducir la latencia.
• Explorá integraciones con Prometheus para que el agente también lea métricas del cluster.

Fuentes

• Building a Cluster-Aware AI Agent with Kubernetes, Argo CD, and GitOps (CNCF Blog, 2026)
• Repo de referencia del proyecto