Saltar a contenido

Estrategia Q3 — IaC para el smart home del usuario (v1)

IaC pragmático para la arquitectura essentials/experimental sin k8s. No hay un role Ansible oficial que cubra HAOS (es appliance), así que el plan separa: HA Yellow gestionado mínimamente vía git de configs + backups; mini-PC gestionado fully vía Ansible + Docker Compose. Todo bajo el principio ../concepts/everything-is-code.

Contexto

El usuario explícitamente pidió "treat as software engineering" y "IaC". Esta página define qué se gestiona, con qué tool, dónde vive en git. Es el contrato técnico entre el código del repo y los servicios corriendo.

Contenido

Por componente

HA Yellow (essentials, HAOS)

  • Install method: HAOS appliance. NO se gestiona via Ansible — es flasheado-via-imagen.
  • Config de HA: role bellackn/ansible-role-hass-control (ver ../sources/bellack-hass-ansible) que sincroniza bidireccionalmente vía HA API. Download mode para "yo edito en UI, sync a repo". Upload mode para "edito en repo, aplico a HA". Reemplaza el patrón scp y supera el role oficial deprecated.
  • Backups: scheduled HA backup → upload a NAS / S3 via Google Drive Backup addon o equivalente.
  • Updates de HAOS: manualmente vía UI o ha os update desde SSH addon (ver ../entities/ha-cli).
  • Z2M config: bind mount también → git.

Lo que NO va en git para el Yellow: - Secrets (tokens, passwords) — usar secrets.yaml en HA + .gitignore. - Database del recorder (binario, va a backup separado). - database.db de Z2M (binario, backup separado).

Mini-PC (experimental + observability + agente)

  • Host install: Debian fresh + Ansible from cold start.
  • Ansible roles a tener (custom o de Galaxy):
  • docker — instalar Docker engine.
  • docker-compose-deploy — pull repo, run compose up.
  • unattended-upgrades — patches del OS automáticos.
  • ssh-hardening — keys-only, no passwords.
  • monitoring-stack — Loki + Promtail + Grafana + Prometheus + Gatus.

  • agent-setup — instala Claude Code + creds + cron job.

  • Docker Compose files en git por servicio:

  • compose/homeassistant.yml (HA Container, twin).
  • compose/zigbee2mqtt.yml (si se separa Z2M del Yellow eventualmente).
  • compose/monitoring.yml (Loki, Prometheus, Grafana, Gatus).
  • compose/agent.yml (Claude Code worker o equivalente).

  • Cada servicio con pin de versión + healthcheck.

  • Secrets: Ansible Vault (encrypted YAML en git) o sops + age. Decidir según preferencia.

Repo layout

homelab/
├── README.md                              # arranque rápido
├── ansible/
│   ├── inventory.yml
│   ├── playbooks/
│   │   ├── bootstrap-mini-pc.yml         # cold start mini-PC
│   │   ├── update-services.yml
│   │   └── apply-monitoring.yml
│   ├── roles/
│   │   ├── docker/
│   │   ├── monitoring-stack/
│   │   └── agent-setup/
│   └── vault/
│       └── secrets.yml                    # encrypted
├── compose/
│   ├── homeassistant.yml                  # HA Container (twin)
│   ├── monitoring.yml
│   └── agent.yml
├── home-assistant/                         # bind mount del Yellow
│   ├── automations.yaml
│   ├── scripts.yaml
│   ├── configuration.yaml
│   ├── packages/
│   └── ...                                # sin secrets
├── zigbee2mqtt/
│   └── configuration.yaml                  # template, sin coordinator binary
├── esphome/
│   ├── living-room-sensor.yaml
│   ├── kitchen-multisensor.yaml
│   └── ...
├── monitoring/
│   ├── prometheus.yml
│   ├── loki-config.yml
│   ├── promtail-config.yml
│   ├── gatus.yml
│   └── grafana-dashboards/
│       └── *.json
├── agent/
│   ├── prompts/
│   │   ├── system-skills.md
│   │   └── failure-mode-playbooks.md
│   └── cron-schedule.txt
└── docs/
    ├── decisions/                          # ADRs
    └── postmortems/

Workflow para cambios

local edit → commit → push → CI (lint + tests) → merge a main →
  → para mini-PC: cron de pull + compose up
  → para HA Yellow: scp manual o vía agente (patrón Beguelin)

Adopción incremental

Alineado con la trayectoria del agente AI:

Paso Qué se construye Cuándo
1 Repo git creado, config actual del Yellow committed Día 1
2 Ansible inventory + bootstrap-mini-pc playbook Semana 1
3 Compose de monitoring desplegado en mini-PC vía Ansible Semana 2
4 HA Container desplegado como twin en mini-PC Semana 2-3
5 Compose de agent desplegado, perímetro mes 1 Semana 3-4
6 CI básico (lint + ha check-config) en GitHub Actions Semana 4
7 Z2M config templating via Ansible Mes 2
8 Esphome CLI en CI para build/check de configs Mes 2

Lo que NO se construye

  • Terraform: no aplica sin Proxmox. Si en el futuro hay Proxmox, se reconsidera.
  • GitOps con ArgoCD/Flux: aplicaba con k8s; sin k8s, el equivalente es git pull && docker compose up -d en cron.
  • CI runner self-hosted: GitHub Actions free tier alcanza.

Conexión con principios

Relaciones

Citas / evidencia

Abierto / gaps

  • Ingerir bellackn/ansible-role-hass-control para patrón concreto de gestión de configs HA vía API (mejor que scp para algunos casos).
  • Definir secret management: Ansible Vault vs sops + age. Por defecto recomiendo sops + age (más moderno, mejor UX).
  • ¿Cómo se versionan los add-ons del Yellow declarativamente? HAOS no parece tener un manifest.
  • Patrón concreto de drift detection: cron job que compara ha-yellow:/config con repo, alerta si diverge.