docker/docs/ansible-workflows.md

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:

linux:
  hosts:
    my-host:
      ansible_host: my-host.local

Validation commands

Run from repository root:

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:

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.