Self-healing infrastructure — adaptada al setup del usuario (sin k8s)¶

Traducción de la reference architecture de madebynathan (../sources/madebynathan-self-healing-2026-02) al setup concreto del usuario, respetando dos constraints duros: (1) k8s queda fuera — confirmado 2026-05-20 — y (2) la meta operativa es "smart home invisible, no tinkering, agentes IA hacen el trabajo". El resultado es una arquitectura de 5 capas equivalente al original pero con Docker Compose en vez de K3s, y con el agente AI como protagonista (no como capa opcional).

Contexto¶

Esta página cierra la decisión de "cómo aplicar self-healing al smart home del usuario". El north-star: una vez configurado, no tinkering. Eso obliga a que cada componente cumpla dos criterios: (1) reduce tinkering futuro, (2) es invisible una vez puesto. K8s falla ambos. Docker Compose + agentes los cumple.

Contenido¶

Las 5 capas, traducidas¶

Capa madebynathan	Adaptación al usuario	Justificación
1. Proxmox (hypervisor)	Opcional: si ya hay un mini-PC, Proxmox no es obligatorio. Alternativas: Debian/Ubuntu plano con Docker, o NixOS si el usuario quiere full declarativo.	Proxmox es excelente pero agrega una capa de tinkering propia (upgrades de Proxmox, ZFS, LXC). Si se justifica por snapshots fáciles → sí. Si es por "todos lo usan" → no.
2. IaC (Terraform + Ansible)	Ansible obligatorio. Terraform opcional.	Sin Proxmox no hay para qué Terraform. Ansible gestiona el host (Docker engine, healthchecks, secrets, backups).
3. Orquestación de servicios	Docker Compose, NO K3s. Healthchecks declarativos + restart policies + dependencies entre servicios.	Compose es declarativo, soporta healthchecks, restart-on-failure, y `depends_on` con condition. Cubre el 80% de lo que querés sin la complejidad lateral.
4. Monitoring	../entities/gatus + Prometheus + Loki + Grafana.	Idéntico a madebynathan. Gatus es la primera línea (binary health), Prometheus/Loki para detalle. Todos corren en Docker Compose.
5. AI brain	Agente AI con acceso al stack — opciones: OpenClaw, agente custom basado en Claude SDK, o Claude Code con MCP a HA + acceso SSH. Ésta es la pieza central, no opcional.	El usuario explicitó que la meta es agent-managed. La capa 5 deja de ser "force multiplier" opcional y pasa a ser el corazón de la arquitectura.

Arquitectura física propuesta¶

┌────────────────────────────────┐    ┌──────────────────────────────────┐
│ HA Yellow (essentials)         │    │ Mini-PC / NUC (experimental)     │
│ ────────────────────────────── │    │ ──────────────────────────────── │
│ HAOS appliance                 │    │ Debian + Docker Compose          │
│ - HA Core (luces, calefacción) │◄───┤ - HA Container (canary, beta)    │
│ - Z2M add-on (Zigbee)          │MQTT│ - Z2M (espejo opcional)          │
│ - Mosquitto                    │    │ - Mosquitto (bridge)             │
│ - Backups automáticos          │    │ - Prometheus + Loki + Grafana    │
│ - Smoke tests post-upgrade     │    │ - Gatus (chequea ambos hosts)    │
└────────────────────────────────┘    │ - Agente AI (LXC o container)    │
                                      │ - Repo git con Ansible/Compose   │
                                      └──────────────────────────────────┘
                                                     │
                                                     ▼
                                            ┌────────────────────┐
                                            │ Repo git (GitHub)  │
                                            │ - Compose files    │
                                            │ - Ansible roles    │
                                            │ - HA config bind   │
                                            │ - ESPHome configs  │
                                            │ - Postmortems      │
                                            └────────────────────┘

Separación essentials / experimental — qué corre dónde¶

Componente	Host	Por qué
HA core (luces, cerraduras, calefacción)	HA Yellow / HAOS	Es lo que ya funciona. Snapshots nativos. UI restore. Aplica ha-upgrade-reliability-strategy.
Z2M (radio Zigbee)	HA Yellow add-on (default) o mini-PC con coordinator dedicated (si se quiere physical separation)	Razón para separar: si el experimental rompe Z2M, no afecta a las luces críticas. Razón para no separar: re-pair de devices es caro. Default: dejar en Yellow hasta tener razón concreta.
HA Container (canary)	Mini-PC	Channel beta opcional, sin essentials. Detecta breaking changes antes de que toquen el Yellow.
Prometheus / Loki / Grafana	Mini-PC	El Yellow tiene recursos limitados; no contaminarlo.
Gatus	Mini-PC	Chequea ambos hosts desde fuera. Si Gatus mismo cae, Prometheus self-monitors.
Agente AI	Mini-PC (container o LXC)	Acceso SSH al Yellow + acceso local al mini-PC + acceso al repo git.
ESPHome dashboard	Mini-PC	OTA flow a devices ESPHome sin pasar por el Yellow.

Adopción incremental — qué primero¶

Regla: ningún paso obliga al siguiente. Si te detenés en el paso 3, ya tenés 70% del valor.

Repo git con HA config actual del Yellow (1 día). Bind mount + commit + push. Empezás a tener historial.
Mini-PC con Docker Compose vacío (1 día). Aún sin servicios. Ansible role mínima para tener Docker + ssh keys + repo cloned.
Prometheus + Grafana + Loki + Gatus en el mini-PC (1-2 días). Chequeás el Yellow desde afuera. Loki recibe los logs de HA si Promtail está configurado en el Yellow.
HA Container en el mini-PC apuntando a beta channel (1 día). Sin migrar nada del Yellow — es paralelo. Sirve de canary.
Agente AI con acceso de lectura primero (1-2 días). Ejecuta kubectl... perdón, ejecuta health checks via Gatus API, lee logs Loki, reporta a Telegram. Sin ejecutar fixes todavía.
Agente AI con perímetro autónomo limitado (semanas). Empieza con: restart de containers caídos, cleanup de logs viejos, renew de certs. Cada acción documentada. Ver ../concepts/ai-as-operator.
Expandir perímetro autónomo (meses). Cuando confiás en el agente, agregás más acciones. Las prohibidas para siempre quedan en lista negra.

Lo que esta arquitectura NO requiere¶

❌ Kubernetes / K3s.
❌ ArgoCD / Flux.
❌ Service mesh.
❌ Cert-manager (Traefik o nginx con acme.sh alcanzan).
❌ Múltiples hosts (mini-PC + Yellow alcanza; un tercer host es opcional).
❌ Migrar todo a IaC el día 1 (incremental).

Lo que sí requiere (no negociable)¶

✅ Repo git con TODO el config no-secreto.
✅ Backups verificables y automatizados.
✅ Healthchecks binarios para los essentials.
✅ Logs centralizados (sin esto, el agente no puede diagnosticar).
✅ Política explícita de "qué puede el agente" — sin esto, AI as owner por defecto, lo que rompe el modelo.

Métricas de éxito alineadas a la meta "invisible"¶

Métrica	Objetivo	Cómo medir
Días sin intervención humana	> 30 días en promedio (essentials)	Manual log de "tuve que tocar algo X día"
% incidentes resueltos por el agente sin escalar	> 70% después de 6 meses	Postmortems del agente
MTTR sin agente vs MTTR con agente	Ratio > 3x mejora	Comparar antes/después
Sorpresas operativas / mes	< 1	Cualquier comportamiento que el usuario tuvo que diagnosticar
Días desde último cambio manual al config	Trending up	El agente debería estar manteniendo el repo, no el humano

Relaciones¶

Implementa: ../concepts/self-healing-infrastructure (la abstracción) sobre el setup concreto del usuario.
Aplica: ../concepts/ai-as-operator y ../concepts/everything-is-code.
Apoya: Q1 (essentials/experimental), Q3 (IaC), Q5 (observabilidad), Q10 (AI tooling) — los amarra todos en una sola arquitectura.
Reemplaza: el patrón "harden HA Container a mano" — acá HA Container es solo una pieza más.
Depende de: install-method-decision-2026 (HAOS Yellow para essentials + HA Container en mini-PC para experimental — esta página confirma la decisión).
Predecesor de: q10-ai-tooling-strategy-v1 (la siguiente página detalla el plan del agente).

Citas / evidencia¶

"que sea más auto atendido y manejado por agentes IA. Quiero un smart home que funcione. Ojalá invisible. No quiero estar tinkering with it" — usuario, mensaje 2026-05-20. Ver spec del proyecto sección Notas locales.
Reference architecture de las 5 capas — ../sources/madebynathan-self-healing-2026-02.

Abierto / gaps¶

Elegir el agente concreto: OpenClaw (más maduro, requiere ingerir docs propias) vs custom con Claude SDK (más adaptado, requiere construir). Decidir después de ingerir entities/openclaw enriquecido.
Política de seguridad del agente sobre el HA Yellow: ¿acceso de sólo lectura inicial? ¿restart-only? Definir cuando se aborde Q10 estrategia.
Patrón concreto de MQTT bridge entre el Yellow y el mini-PC. Buscar source que documente el caso.
Snapshot del HA Yellow al mini-PC: ¿hay un patrón de "off-site backup" automatizado? Para evitar dependencia del eMMC del Yellow.
Cuándo desconectar el HA Yellow (si pasa). Esta arquitectura asume Yellow indefinido. Si el cutoff de HAOS lo deja sin updates, hay que migrar HA → mini-PC y el Yellow queda como puente Zigbee/BT puro.