Problema

En entornos de producción y homelabs es habitual alternar entre documentación estática, dashboards de métricas y la terminal para ejecutar tareas. Esa fragmentación genera una visión parcial del estado real del sistema: el diagrama muestra la arquitectura, pero no refleja fallos; el monitor indica problemas, pero no muestra dónde están ubicados; la shell permite arreglar cosas, pero sin contexto visual. Cuando el equipo necesita entender rápidamente qué servicio está caído, qué nodo está saturado o cómo se relacionan los componentes, se pierde tiempo navegando entre varias herramientas. El reto es disponer de una única fuente de verdad que combine la topología, el estado en tiempo real y la capacidad de edición declarativa.

Causa

Los principales factores que provocan esta desconexión son:

  1. Documentación fuera de línea – Los diagramas se exportan a PDF o PNG y nunca se actualizan automáticamente. Cualquier cambio en la infraestructura queda desincronizado.
  2. Monitoreo aislado – Herramientas como Prometheus o Grafana se enfocan en métricas, pero no ofrecen un mapa visual que relacione métricas con nodos y servicios.
  3. Gestión de configuración distribuida – Cada ingeniero mantiene su propio archivo de inventario o script de despliegue, lo que genera divergencias y dificulta la colaboración.
  4. Falta de control de acceso a credenciales – Cuando los checks usan claves SSH almacenadas en laptops, la rotación de claves y la auditoría se vuelven problemáticas.
  5. Ciclo de prueba‑error en la terminal – Sin una vista de alto nivel, los operadores prueban comandos al azar, lo que aumenta la superficie de error.

Estos patrones aparecen tanto en homelabs con Raspberry Pi como en clústers Kubernetes gestionados internamente.

Solución

Una estrategia reutilizable consiste en tratar el diagrama como la capa operativa de la infraestructura. En lugar de generar un PDF estático, se mantiene un archivo YAML que describe los nodos, sus relaciones y los checks que deben ejecutarse. Un agente (daemon) lee ese YAML, ejecuta health checks mediante SSH o kubectl, y actualiza el estado directamente en el mismo archivo. La UI, ya sea una aplicación de escritorio o un servidor web, renderiza el mapa en tiempo real y permite editar la topología con cualquier editor de texto (por ejemplo, Vim). Los cambios se versionan con Git, lo que brinda historial, revisiones y rollback.

Componentes clave:

  • Archivo de topología YAML – Define nodos, conexiones y comandos de verificación.
  • Daemon de ejecución – Programa ligero (Rust, Go, etc.) que recorre el YAML, ejecuta los checks y escribe el resultado (healthy, degraded, failed) en el mismo documento.
  • Frontend interactivo – Renderiza el canvas, colorea nodos según su estado y permite arrastrar/soltar para reorganizar la topología.
  • Almacenamiento de credenciales centralizado – El daemon mantiene las claves SSH y los contextos de kubectl en un único host, evitando la dispersión en laptops.
  • Integración con Git – Cada modificación del YAML se comitea automáticamente; los pull‑request sirven como revisión de cambios de arquitectura.

Este enfoque es agnóstico al orquestador: funciona con Docker Compose, Swarm, Kubernetes o cualquier servicio accesible por SSH. La única dependencia es que el daemon pueda ejecutar los comandos declarados.

Cuándo aplicar esta solución

Se recomienda cuando:

  • La infraestructura supera la simple lista de contenedores y tiene dependencias cruzadas (bases de datos, colas, proxies).
  • Se necesita una visión unificada para equipos distribuidos o para uso personal en homelabs.
  • Los cambios de arquitectura son frecuentes y requieren auditoría.
  • Se desea evitar la proliferación de credenciales en máquinas de desarrollo.

No es necesario si:

  • La topología es estática y mínima (uno o dos contenedores) y ya se gestiona con scripts simples.
  • El equipo ya usa una solución de IaC (Terraform, Pulumi) con visualizador integrado y no necesita un mapa interactivo.
  • No hay requisitos de monitoreo en tiempo real; basta con alertas por correo o Slack.

Código

# ejemplo de topología mínima en YAML
nodes:
  - name: pi5
    type: host
    address: 192.168.1.10
    ssh_user: pi
    checks:
      - cmd: "docker ps | grep -q nginx"
        description: "Nginx container running"
  - name: k8s-master
    type: k8s
    context: homelab
    checks:
      - cmd: "kubectl get pods -n monitoring -l app=prometheus -o jsonpath='{.items[0].status.phase}'"
        expected: "Running"
links:
  - source: pi5
    target: k8s-master
    label: "API"

El daemon lee este archivo, ejecuta cada cmd y actualiza un campo status bajo cada nodo. La UI muestra pi5 en verde si el contenedor Nginx está activo, o en rojo si el comando devuelve error.


## Verificación
1. **Iniciar el daemon** – `reticle-daemon --config topology.yaml --git-repo /path/to/repo`.
2. **Observar la UI** – Acceder a `http://localhost:8080` y confirmar que los nodos aparecen con el color correspondiente.
3. **Provocar un fallo** – Detener el contenedor Nginx (`docker stop nginx`) y esperar 30 s. El nodo debe pasar a rojo automáticamente.
4. **Revertir el cambio** – Reiniciar el contenedor y comprobar que el color vuelve a verde sin recargar la página.
5. **Revisar Git** – Ejecutar `git log -p topology.yaml` para ver el diff que refleja el cambio de estado.

## Notas adicionales
- **Escalabilidad**: el daemon procesa checks en paralelo; ajusta el número de workers según la cantidad de nodos para evitar sobrecarga de SSH.
- **Seguridad**: limita el acceso al daemon mediante firewall interno y usa claves SSH con passphrase; el daemon nunca expone la clave a la UI.
- **Persistencia de estado**: guarda el último estado en un archivo `.state.yaml` para que la UI pueda cargar rápidamente al iniciar, incluso si el daemon está offline.
- **Extensibilidad**: puedes añadir nuevos tipos de checks (HTTP GET, ping, consultas SQL) simplemente ampliando la sección `checks` con el comando adecuado.
- **Integración CI/CD**: incluye un job que valide la sintaxis del YAML antes de mergear; así evitas que un error de formato rompa el daemon en producción.