Ansible

Ansible is the configuration-management tool for every host that doesn't run Talos Linux. Talos is API-driven and immutable — Ansible would be redundant. K3s nodes, ad-hoc Docker hosts, and the occasional utility VM are all mutable Linux, and that's where Ansible earns its keep.

Source of truth: ansible/ at the repo root.

Where Ansible fits

hardware                                            (a server exists)
   │
   ▼
provision (Tofu / manual install)                   (the OS boots)
   │
   ├──► Talos node?       —— Talos owns it from here
   │
   └──► non-Talos host?   —— Ansible takes over: packages, users, service config
                              │
                              └──► Docker / k3d / K3s start running

The IaC tool and Ansible are complementary: OpenTofu creates the box, Ansible turns it into a useful one.

Roles

Role	Target hosts	What it does
docker-host	any Linux host that should run Docker	Installs the Docker engine + cli, configures daemon options, sets up the docker group, optionally pulls a baseline of images

More roles are added as needed. A role earns its place when it's run on at least two hosts.

Inventory pattern

Inventories live alongside the playbooks under ansible/inventories/<environment>/. Hosts are grouped by role, not by physical location — a "docker_host" group can include the Synology NAS and a K3s node side by side, because what they share is the role.

Conventions

• Idempotent always. Running a playbook twice should be a no-op the second time.
• No state files. Drift detection is --check --diff; if the diff is non-empty, that's the drift.
• Vault for secrets. Ansible Vault wraps anything sensitive; the password lives in a SOPS-encrypted file alongside the playbooks. (See Operations → Secrets for how the SOPS layer is keyed.)
• Roles before tasks. A playbook should mostly compose roles, not declare tasks inline. Tasks-in-playbooks are a smell that wants extracting.

Day-2 commands

# Dry-run against a host group
ansible-playbook -i inventories/home site.yml --limit docker_hosts --check --diff

# Apply
ansible-playbook -i inventories/home site.yml --limit docker_hosts

# Run a single role ad-hoc against one host
ansible-playbook -i inventories/home site.yml --limit synology --tags docker-host

Where to look next

• Docker hosts — the runtime that the docker-host role provisions
• K3s — Ansible could also bootstrap K3s nodes (currently scripted)
• Operations → Secrets → SOPS — the same pattern that keeps Tofu tokens and Ansible Vault passwords out of plaintext