The first Ansible playbook grew to 800 lines, the inventory file has all the production secrets pasted in vars:, and three projects copy the same Nginx role with three slightly different bugs. This article is the refactor: a roles-based layout, a properly-structured inventory with group_vars/ and host_vars/, and the conventions that let two operators edit the same repo without colliding.
How to verify
From the repo root, the directory layout tells you a lot:
tree -L 2 -a -I '.git'
ansible-inventory -i inventory/production --graph
ansible-config dump --only-changed
ansible-lint
ansible-inventory --graph prints the host/group hierarchy as Ansible actually sees it after merging group and host vars. ansible-lint catches anti-patterns (deprecated modules, missing tags, naked tasks) before they hit CI.
What’s happening
A role is a self-contained Ansible component with a fixed directory structure: tasks/main.yml, handlers/main.yml, defaults/main.yml, vars/main.yml, templates/, files/, meta/main.yml, and optionally tests/. The interface is the variables a role consumes; the contract is documented in defaults/main.yml (loose defaults) and meta/main.yml (dependencies). Playbooks become thin — they map hosts to roles and pass tier-specific variables.
The inventory layout that scales has three properties: separate inventories per environment (inventory/production/, inventory/staging/); host variables in host_vars/<hostname>.yml, not inline; and group variables in group_vars/<group>.yml with group_vars/all.yml for cross-cutting concerns. Sensitive group/host vars files end with .vault.yml and are encrypted with Ansible Vault (see /en/knowledge-base/ansible-vault-secrets/).
The procedure
-
Adopt the directory layout. This is the standard the wider community converged on; it is also what
ansible-galaxy initproduces.. ├── ansible.cfg ├── inventory/ │ ├── production/ │ │ ├── hosts.yml │ │ ├── group_vars/ │ │ │ ├── all.yml │ │ │ ├── web.yml │ │ │ └── db.vault.yml │ │ └── host_vars/ │ │ └── web1.example.com.yml │ └── staging/ │ └── hosts.yml ├── roles/ │ ├── common/ │ ├── nginx/ │ └── postgres/ ├── playbooks/ │ ├── site.yml │ └── db.yml └── requirements.yml -
Create the role with
ansible-galaxy init. This stubs out every directory and a sensiblemeta/main.yml.ansible-galaxy init roles/nginx -
Put loose defaults in
defaults/main.ymland tight ones invars/main.yml. Defaults are the lowest precedence — any inventory variable, playbook variable, or extra-var will override them.vars/is high precedence; use it only for values that should not be overridden from outside the role.# roles/nginx/defaults/main.yml nginx_worker_processes: auto nginx_worker_connections: 1024 nginx_keepalive_timeout: 65 nginx_client_max_body_size: 16m -
Pin external roles in
requirements.yml. Galaxy roles drift; Git-sourced roles need pinning to a commit or tag. Re-fetch in CI before each run.# requirements.yml roles: - src: geerlingguy.postgresql version: 4.5.0 collections: - name: community.general version: 8.6.0ansible-galaxy install -r requirements.yml --force -
Thin playbooks. A playbook should describe topology, not implementation.
# playbooks/site.yml - hosts: web become: true roles: - common - { role: nginx, tags: [nginx] } - { role: php-fpm, tags: [php] } - hosts: db become: true roles: - common - postgres -
Separate environments with separate inventories. Pass
-i inventory/productionor-i inventory/stagingexplicitly. Never makeinventory/productionthe default — operators should have to type “production” every time.ansible-playbook -i inventory/staging playbooks/site.yml ansible-playbook -i inventory/production playbooks/site.yml --check --diff -
Wire
ansible-lintandansible-playbook --syntax-checkinto CI. Lint catches stale modules and missing handlers; syntax-check catches the YAML errors that lint misses.ansible-lint playbooks/ roles/ ansible-playbook -i inventory/staging playbooks/site.yml --syntax-check
Common pitfalls
vars:in a playbook overridesdefaults/main.ymlof a role but loses tohost_vars/; the cleanest fix is to put the override at the same precedence level as the source of truth.- Roles with
meta/main.yml: dependencies:re-run their deps in every play that uses them — acommonrole pulled in twice runs twice unless guarded withwhen:. - A role with no
defaults/main.ymland references to{{ undefined_var }}will fail at runtime, not at lint —ansible-lintwill not catch it. inventory/production/hosts.ymlandinventory/staging/hosts.ymlwith the same group names and different members is the right pattern; the same host listed in both inventories is a mistake.- Globbing host names (
web*in a playbook’shosts:) is convenient but obscures intent — a named group is the better signal.
In the engagements we run, the Ansible repo is the source of truth for the long tail of stateful servers — roles, inventories per environment, encrypted group_vars for secrets, and an apply log captured in a central audit trail. See /en/services/managed-operations/.