Estrategia de upgrade reliability — aplicada al setup del usuario¶
Primera síntesis operativa de la pregunta guía Q2: cómo hardenear los upgrades de Home Assistant para que dejen de romper. Combina la pre-update checklist, las best practices y el procedimiento de rollback con la arquitectura essentials/experimental propuesta en install-method-decision-2026.
Contexto¶
Esta página existe para responder concretamente al dolor que motivó este wiki: "Home Assistant rompe en upgrades". No es una recolección de buenas intenciones; es un plan ejecutable con criterios de éxito. La versión final llegará tras ingerir los postmortems community (pendientes en gaps), pero el esqueleto ya es accionable.
Contenido¶
Diagnóstico del problema actual¶
Sin ingerir todavía los postmortems específicos, los factores documentados son:
- HA tiene release mensual (
YYYY.M.0) + parches: ritmo alto, surface alta. - Breaking changes son la norma, no la excepción. El equipo los lista en cada changelog.
- Integrations custom (HACS) lag: cada vez que HA libera una
.0, integrations no oficiales pueden tardar días/semanas en alinearse. - Add-ons updates van separadas: Z2M, Mosquitto, etc. tienen su propio ciclo. Update simultáneo de todo es la receta para no saber qué rompió.
Plan en cuatro capas¶
Capa 1 — Arquitectura (la decisión que más mueve la aguja)¶
- Essentials en ../entities/home-assistant-os sobre HA Yellow (status quo). Channel: stable. Update a los 7-10 días del release. Aplica ha-pre-update-checklist completo + ha-update-best-practices (update incremental).
- Experimental en ../entities/home-assistant-container sobre nodo aparte. Channel: beta (opcional). Update inmediato cuando sale stable nuevo; sirve de canary para el essentials.
- Comunicación entre los dos: MQTT bridge (essentials publica eventos, experimental consume). Si experimental se rompe, essentials sigue funcionando.
Ver install-method-decision-2026 para el detalle.
Capa 2 — Proceso (la pre-update checklist)¶
Cada upgrade del essentials sigue obligatoriamente ha-pre-update-checklist:
- Release notes + breaking changes leídos.
- Compatibilidad de integrations verificada.
- Full backup verificado (no sólo creado).
- Check Configuration pasa.
- Plan de rollback escrito con versión previa anotada.
Lo cumple un script ejecutado por un agente (Q10) o el humano. Idealmente: agente propone, humano aprueba, agente ejecuta.
Capa 3 — Update propiamente dicho¶
- Orden: Core → Supervisor → OS → Add-ons.
- Un componente por sesión. No "todo el sábado a la noche".
- Smoke tests post-update por componente (luces críticas, cerraduras, calefacción, automations de seguridad).
Capa 4 — Si rompe (rollback)¶
Disparador: 1-2 horas sin fix → restore.
Procedimiento: ha-rollback-procedure.
- Opción A (full restore) default para fallos no-aislados.
- Opción B (
ha core update --version) sólo si está claramente aislado al Core.
Métricas de éxito¶
Para saber si el plan funciona, trackear:
| Métrica | Cómo | Objetivo |
|---|---|---|
| Frecuencia de rollback | Notas en repo de configs (Q10) | < 1 por trimestre |
| Tiempo a descubrir issue post-upgrade | Logs + smoke tests | < 30 min |
| MTTR ante upgrade roto | Wall clock desde detect a restore | < 1 hora con full restore, < 30 min con core-only |
| % de upgrades aplicados con pre-checklist completo | Commit history del repo | 100% para essentials, sin obligación para experimental |
| Días desde último upgrade aplicado | Comparar ha core info vs commit history o last_updated en repo |
< 45 días para Core, < 90 días para HAOS — exceder estos umbrales correlaciona con caer en el failure mode "stuck HAOS" (failure-mode-stuck-haos-update-mechanism) |
| Gap de versión vs latest | Query a home-assistant.io + ha core info |
< 2 releases mensuales para essentials |
Lo que esta estrategia no cubre todavía¶
- Failure modes catálogo (qué se rompe típicamente y cómo se detecta). Primera entrada catalogada: failure-mode-stuck-haos-update-mechanism. El catálogo se va poblando con cada postmortem nuevo.
- Anomaly detection en logs post-upgrade (Q5 observability). Por ingerir.
- HACS lag específicamente (Q2 sub-gap). Pending.
- HA Yellow lifecycle ahora que está discontinuado (¿hasta cuándo recibe HAOS updates?). Pending.
Relaciones¶
- Implementa: Q2 (HA upgrade reliability) — primera versión.
- Apoyada por: ha-pre-update-checklist, ha-update-best-practices, ha-rollback-procedure, ../concepts/ha-update-channels.
- Depende de: install-method-decision-2026 (la arquitectura essentials/experimental es prerrequisito de la Capa 1).
- Conecta con: futuras Q3 IaC, Q4 testing, Q5 observabilidad, Q10 AI tooling.
Citas / evidencia¶
-
"Approaching Home Assistant updates with a strategy of preparation, careful execution, and a clear rollback plan transforms them from a potential headache into a routine maintenance task." — ../sources/mastering-ha-updates-rollbacks.
- Migration paths cross-method backup → restore — ../sources/ha-deprecating-core-supervised-2025-05.
Abierto / gaps¶
- Validar las 4 métricas contra los postmortems community que aún no se ingirieron (Q2 alta candidatos).
- Definir el formato exacto del commit message del repo de configs para tracking del histórico de upgrades.
- ¿La capa 1 (essentials/experimental) sobrevive si el usuario decide no tener un segundo nodo? Versión alternativa: "essentials en HAOS Yellow + canary en VM beta efímera".