kevinveenbirkenbachandClaude Opus 5
1647dfb542
The rule named roles/<role>/config/main.yml, which no role has: f65f4d60fb migrated the last one, web-app-pihole, to meta/services.yml and did not carry the README with it. A reader following the sentence found nowhere to put the value.
It now names the two real homes and the property that decides between them. meta/services.yml is overridable, because the inventory's applications block is deep-merged on top of it and lookup('config', ...) reads the result; vars/main.yml is not, because role vars outrank inventory variables. The clause about a value only one role reads today is the case that just went wrong: group_vars/all/19_tor.yml looked harmless for exactly that reason.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1.6 KiB
group_vars/all 📦
This directory contains the Ansible group_vars applied to every host in the inventory. It holds the shared baseline that every role and every host-specific var can build on top of.
Scope 🎯
Variables in this directory MUST apply across all hosts and all roles. Typical examples are the software identity, deployment toggles, domain defaults, the central network and port registries, OIDC and LDAP endpoints, design tokens, and resource defaults.
Role-specific configuration MUST NOT live here, even when only one role reads it today. Such values belong in the corresponding role:
roles/<role>/meta/services.ymlfor anything an operator may override, because the inventory'sapplications.<role>block is deep-merged on top of it andlookup('config', application_id, '<path>')reads the result.roles/<role>/vars/main.ymlfor values derived from that configuration, and for those the role fixes. Role vars outrank inventory variables, so a value placed here cannot be overridden per host.
File naming and load order 🔢
Files MUST use the pattern NN_<topic>.yml, where NN is a zero-padded two-digit numeric prefix. Ansible loads files in lexicographic order, so the prefix determines the load order and lets later files reference values defined earlier.
Prefixes MUST be unique and sequential without gaps. When you add, remove, or reorder a file, you MUST update every hard-coded reference in code, tests, and documentation to keep the sequence consistent. You SHOULD grep for group_vars/all/<old-name>.yml before renaming.