Skip to content

Running Ansible

Comandos canónicos para ejecutar playbooks desde la Mac. Ansible se usa en modo híbrido: el modo principal es ansible-pull (cada nodo se auto-aplica vía cron cada 15min), pero también se puede correr ansible-playbook push-mode desde la Mac para iteración rápida y dry-runs.

Setup local (una sola vez)

Instalación

bash brew install ansible sops age

Keys + env

```bash mkdir -p ~/.config/sops/age

Si ya tienes una key generada, copiarla aquí. Si no:

age-keygen -o ~/.config/sops/age/keys.txt chmod 600 ~/.config/sops/age/keys.txt ```

Añadir a ~/.zshrc (o ~/.zshenv):

bash export SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" export ANSIBLE_CONFIG="$HOME/homelab-infra/ansible/ansible.cfg"

source ~/.zshrc.

SSH

Los nodos asumen autenticación por key (no password). Verifica:

bash ssh pmx-50 'hostname' ssh pmx-51 'hostname' ssh [email protected] 'hostname'

Si falla, añadir tu pubkey a ~/.ssh/authorized_keys del usuario destino. No subir keys a Vaultwarden ni al repo.

Colecciones Ansible

bash cd ~/homelab-infra/ansible ansible-galaxy install -r requirements.yml

requirements.yml incluye al menos community.sops, community.general, ansible.posix.

Comandos canónicos

Dry-run global

bash cd ~/homelab-infra/ansible ansible-playbook playbook.yml --check --diff

--check: no aplica, solo simula. --diff: muestra diff de archivos cambiados.

Dry-run limitado a un grupo/host

bash ansible-playbook playbook.yml --check --diff --limit proxmox_nodes ansible-playbook playbook.yml --check --diff --limit pmx-50 ansible-playbook playbook.yml --check --diff --limit vm208

Grupos definidos en inventory.yml:

  • proxmox_nodes: pmx-50, pmx-51
  • caddy_ha: lxc-270, lxc-271
  • observability: vm208
  • all: todos

Aplicar (push)

Quitar --check:

bash ansible-playbook playbook.yml --diff --limit proxmox_nodes

Push mode + ansible-pull cron

Si haces push manual y el cron de ansible-pull corre justo después con una rama remota distinta, sobrescribe tu cambio. Para evitarlo: 1. Empuja primero a Git (git push). 2. Luego corre ansible-playbook (que tira del estado de Git).

Solo tareas con un tag

bash ansible-playbook playbook.yml --tags caddy ansible-playbook playbook.yml --tags observability --check

Tags actuales (por rol):

  • baseline — usuarios, ssh, motd, base packages
  • proxmox — config PVE (/etc/pve/*, jobs.cfg)
  • caddy — config Caddy LXC 270/271 + keepalived
  • observability — Loki, Prometheus, Promtail
  • secrets — distribución de SOPS-decrypted files

Forzar pull en un nodo (lo que hace el cron)

bash ssh pmx-50 'ansible-pull -U https://github.com/monxas/homelab-infra.git \ -i ansible/inventory.yml ansible/playbook.yml \ --limit pmx-50'

Útil para validar que el repo está reflejado en disk sin tener que esperar 15min.

Roles existentes

Role Hosts Qué hace
baseline all Usuarios, sudoers, SSH config, NTP, base packages
proxmox_node proxmox_nodes /etc/pve/datacenter.cfg, jobs.cfg, sysctl tuning, kernel pinning
observability_collector observability Promtail, node_exporter, scrape config
caddy_lxc caddy_ha (TBD) Caddyfile base, keepalived, managed.caddy sync
secrets_distribute all Decrypt + drop secretos SOPS en /etc/<service>/ con perms 600

Workflow típico

  1. Edita un template/config en el repo: vim ansible/templates/grafana.ini.j2.
  2. Dry-run: ansible-playbook playbook.yml --check --diff --limit vm208 --tags observability.
  3. Revisa el diff. Si pinta bien:
  4. Aplica: misma línea sin --check.
  5. Verifica: ssh vm208 'systemctl status grafana'.
  6. Commit + push: git add ansible/templates/grafana.ini.j2 && git commit -m '...' && git push.

Troubleshooting

Síntoma Fix
community.sops not found ansible-galaxy collection install community.sops
Failed to get the data key en lookup SOPS Tu key no es recipient del archivo. Ver SOPS key rotation
Permission denied (publickey) a un nodo SSH agent sin la key cargada: ssh-add ~/.ssh/id_ed25519
Cambios no se aplican aunque corra sin --check Tag equivocado, o when: filtro excluye el host. -vvv para ver decisiones
kernel of pve-1 changed warning Reboot pendiente del host. Ver Kernel jump