# Ansible Foundation (Phase 1)

This directory provides a minimal Ansible bootstrap for this repository.

## Purpose

- Establish a maintainable inventory/configuration foundation for hosts and devices.
- Support gradual host onboarding and validation workflows.
- Keep boundaries clear with existing Compose and Terraform authorities.

This is intentionally a **foundation stage**, not full production automation.

## Boundaries

- Docker runtime authority remains in Compose files and `services-up.sh`.
- Terraform remains the primary structured infrastructure inventory/reconciliation layer.
- Ansible here is a complementary configuration/inventory layer.
- NixOS and network gear management are not authoritative through Ansible yet.

## Structure

- `ansible.cfg` - local defaults for inventory, collections, and output behavior.
- `inventory/hosts.yml` - YAML inventory scaffold with starter groups.
- `inventory/group_vars/` - shared/group variables.
- `inventory/host_vars/` - per-host variables.
- `playbooks/ping.yml` - minimal syntax/connection test playbook.
- `playbooks/dns-inventory.yml` - local-only Dynu DNS read-only inventory wrapper.
- `collections/requirements.yml` - lightweight baseline collections.
- `roles/` - reserved for future incremental role adoption.

## Basic commands

Run from repository root:

```bash
ansible --version
ansible-lint --version
ansible-galaxy collection install -r infrastructure/ansible/collections/requirements.yml -p infrastructure/ansible/collections
ansible-inventory -i infrastructure/ansible/inventory/hosts.yml --list
ansible-playbook -i infrastructure/ansible/inventory/hosts.yml infrastructure/ansible/playbooks/ping.yml --syntax-check
ansible-playbook -i infrastructure/ansible/inventory/hosts.yml infrastructure/ansible/playbooks/dns-inventory.yml --syntax-check
```

## Secrets and safety

- Do not commit real credentials or private keys.
- Put sensitive per-host variables in local, untracked files or a future vault approach.
- Keep host and device entries factual; avoid speculative production entries.