Manage routine operations through Ansible

2026-08-03 16:01:35 +08:00
parent b73125e5bc
commit 7a9acb4f7c
25 changed files with 353 additions and 59 deletions
@@ -0,0 +1,61 @@
+# Runbook: routine operations through Ansible
+
+Run commands from `ansible/`. The inventory forces IPv4 and uses the `windy`
+account with sudo. Do a read-only health pass before any reconciliation.
+
+## Health report (read-only)
+
+```bash
+cd ansible
+ansible-playbook playbooks/health-report.yml
+ansible-playbook playbooks/health-report.yml --limit mailcow
+ansible-playbook playbooks/health-report.yml --limit matrix
+```
+
+This invokes the existing server-local checks and prints sanitized output; it
+does not expose secrets or alter application configuration. A warning or
+critical health result makes the play fail deliberately.
+
+If the local health check has not been installed yet, deploy it first:
+
+```bash
+ansible-playbook playbooks/healthchecks.yml
+ansible-playbook playbooks/matrix-healthchecks.yml
+```
+
+## Reconcile a known Compose service (mutating)
+
+Only use this after a reviewed configuration change that requires a recreate.
+The allowlist and flags are in inventory; arbitrary commands and service names
+are rejected. Run one host at a time and re-run the health report afterwards.
+
+```bash
+# PowerDNS auth after its configuration changed
+ansible-playbook playbooks/compose-reconcile.yml --limit powerdns \
+  -e '{"service_reconcile_confirm": true, "service_reconcile_targets": ["auth"]}'
+
+# Vaultwarden, including the documented Traefik refresh for a post-recreate 404
+ansible-playbook playbooks/compose-reconcile.yml --limit vaultwarden \
+  -e '{"service_reconcile_confirm": true, "service_reconcile_targets": ["vaultwarden"], "service_reconcile_restart_traefik": true}'
+
+# Poweradmin after changing its environment or Traefik labels; restart its
+# Traefik container only when the UI is returning 404
+ansible-playbook playbooks/compose-reconcile.yml --limit powerdns \
+  -e '{"service_reconcile_confirm": true, "service_reconcile_targets": ["poweradmin"], "service_reconcile_restart_traefik": true}'
+```
+
+Do not use this playbook for a Mailcow update, database migration, DNS record
+change, or secret rotation. Those operations require their dedicated reviewed
+and, where appropriate, interactive procedures.
+
+## Host-level maintenance
+
+These playbooks cover every inventory host, including the Matrix K3s node:
+
+```bash
+# Read-only pending package and reboot report
+ansible-playbook playbooks/maintenance-preview.yml
+
+# Baseline observations; logrotate management remains opt-in
+ansible-playbook playbooks/baseline.yml
+```