beatz174-bit
73 lines
2.6 KiB
Markdown
73 lines
2.6 KiB
Markdown
# 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.
|