Skip to content

Ansible roles and inventory layout that scale past one repo

Move from a single playbook to a roles-based repo with proper inventory, group_vars and host_vars structure — without painting yourself into a corner.

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

  1. Adopt the directory layout. This is the standard the wider community converged on; it is also what ansible-galaxy init produces.

    .
    ├── 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
  2. Create the role with ansible-galaxy init. This stubs out every directory and a sensible meta/main.yml.

    ansible-galaxy init roles/nginx
  3. Put loose defaults in defaults/main.yml and tight ones in vars/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
  4. 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.0
    ansible-galaxy install -r requirements.yml --force
  5. 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
  6. Separate environments with separate inventories. Pass -i inventory/production or -i inventory/staging explicitly. Never make inventory/production the 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
  7. Wire ansible-lint and ansible-playbook --syntax-check into 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 overrides defaults/main.yml of a role but loses to host_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 — a common role pulled in twice runs twice unless guarded with when:.
  • A role with no defaults/main.yml and references to {{ undefined_var }} will fail at runtime, not at lint — ansible-lint will not catch it.
  • inventory/production/hosts.yml and inventory/staging/hosts.yml with 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’s hosts:) 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/.