# 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.