Add phase-1 Ansible foundation and validation scaffolding

2026-04-21 12:07:29 +10:00
parent 862ddd42f8
commit e11dc22999
15 changed files with 277 additions and 9 deletions
@@ -0,0 +1,72 @@
+# Ansible Workflows (Bootstrap / Phase 1)
+
+Ansible is being introduced as a minimal, maintainable foundation for host/device inventory and future configuration workflows.
+
+## Why introduce Ansible now
+
+- The repository already has strong runtime and infrastructure boundaries (Compose + Terraform).
+- A small Ansible baseline allows gradual host onboarding without forcing immediate large-scale automation.
+- It enables safe validation workflows (`inventory --list`, playbook syntax checks) before real execution.
+
+## What Ansible is for in this repository (right now)
+
+- YAML inventory structure for hosts/devices to be onboarded over time.
+- Group and host variable scaffolding for future incremental adoption.
+- Validation-oriented starter playbook and local tooling checks.
+
+## What Ansible is not for yet
+
+- Replacing Docker Compose runtime authority.
+- Replacing Terraform inventory/reconciliation authority.
+- Becoming the current source of truth for NixOS host management.
+- Becoming the current source of truth for all network automation.
+
+## Directory layout
+
+- `infrastructure/ansible/ansible.cfg`
+- `infrastructure/ansible/inventory/hosts.yml`
+- `infrastructure/ansible/inventory/group_vars/`
+- `infrastructure/ansible/inventory/host_vars/`
+- `infrastructure/ansible/playbooks/ping.yml`
+- `infrastructure/ansible/collections/requirements.yml`
+
+## Add a host (gradual onboarding)
+
+1. Open `infrastructure/ansible/inventory/hosts.yml`.
+2. Add the host under an appropriate group (`linux`, `network`, `virtualization`, or `nixos`).
+3. Add non-sensitive defaults under group vars only when shared across hosts.
+4. Add host-specific values in `inventory/host_vars/<hostname>.yml`.
+5. Keep secrets out of committed files.
+
+Example pattern:
+
+```yaml
+linux:
+  hosts:
+    my-host:
+      ansible_host: my-host.local
+```
+
+## Validation commands
+
+Run from repository root:
+
+```bash
+ansible --version
+ansible-lint --version
+ansible-inventory -i infrastructure/ansible/inventory/hosts.yml --list
+ansible-playbook -i infrastructure/ansible/inventory/hosts.yml infrastructure/ansible/playbooks/ping.yml --syntax-check
+```
+
+Install/update baseline collections:
+
+```bash
+ansible-galaxy collection install -r infrastructure/ansible/collections/requirements.yml -p infrastructure/ansible/collections
+```
+
+## Guardrails for future expansion
+
+- Keep changes incremental (one host/group/playbook change at a time).
+- Prefer simple playbooks before introducing roles.
+- Add network-platform/NixOS-specific logic only when those boundaries are explicitly adopted.
+- Keep documentation aligned with source-of-truth boundaries when Ansible authority evolves.