Role anatomy and where roles are found · Ansible

A role is a directory with a conventional layout. There is no registration step, no manifest listing its contents, and no import statement naming its files. You write roles: [webapp] in a play, and Ansible walks a fixed set of subdirectory names underneath roles/webapp/, loading whatever it finds.

That is the whole mechanism, and it is worth stating plainly because the convention does all the work. Nothing tells you that defaults/main.yml holds variables — the path is the declaration. A file in the wrong directory is not an error. It is silence.

The directories

ansible-galaxy init writes the canonical skeleton. This is the fastest way to see what the convention actually is, rather than what you remember of it:

Read-only / Safegenerate a role skeleton— Creates a directory tree under the current working directory. Writes nothing outside it and touches no managed host.

ansible-galaxy init webapp
find webapp -type f | sort

Read-only / Safethe skeleton ansible-core 2.21.3 produces— Executed. Note that files/ and templates/ are created as empty directories - they have no main.yml because nothing is auto-loaded from them.

$ ansible-galaxy init webapp && find webapp | sort

- Role webapp was created successfully
webapp
webapp/README.md
webapp/defaults
webapp/defaults/main.yml
webapp/files
webapp/handlers
webapp/handlers/main.yml
webapp/meta
webapp/meta/main.yml
webapp/tasks
webapp/tasks/main.yml
webapp/templates
webapp/tests
webapp/tests/inventory
webapp/tests/test.yml
webapp/vars
webapp/vars/main.yml

Six directories carry a main.yml that Ansible loads by itself when the role runs. Two do not, and the difference is the thing people get wrong:

Directory	Auto-loaded `main.yml`?	What it is for
`tasks/`	Yes — the role’s entry point	The tasks the role runs
`handlers/`	Yes	Handlers, merged into the parent play’s namespace
`defaults/`	Yes	Variables at the bottom of precedence — the role’s public interface
`vars/`	Yes	Variables high in precedence — internal constants
`meta/`	Yes	Role metadata: dependencies, `allow_duplicates`, Galaxy info
`tests/`	No — not part of a run	A sample inventory and playbook for the role author
`files/`	No	Changes where `copy`, `script` and `unarchive` look for a relative source
`templates/`	No	Changes where `template` looks for a relative source

files/ and templates/ do not load anything. They alter lookup: inside a role, ansible.builtin.template: src=nginx.conf.j2 resolves against roles/webapp/templates/ first. That is why a role’s templates need no path prefix and why moving a task out of a role breaks its src silently.

Three more directories exist and are not in the skeleton, because most roles do not need them:

library/ — modules shipped inside the role, available to it without a collection
module_utils/ — shared Python for those modules
lookup_plugins/, filter_plugins/, action_plugins/ and the rest of the plugin families — plugins scoped to the role

Every main.yml can be a directory of files instead

tasks/main.yml is the entry point, but nothing says it has to be the only file. A role of any size usually reads:

# roles/webapp/tasks/main.yml
- name: install packages
  ansible.builtin.import_tasks: install.yml

- name: write configuration
  ansible.builtin.import_tasks: configure.yml

- name: start and enable the service
  ansible.builtin.import_tasks: service.yml

The sibling files are found relative to tasks/, so no path prefix is needed. Part XXII lesson 5 covers what import_tasks versus include_tasks does to your dry run — the choice is not cosmetic.

Where a bare role name is looked up

roles: [webapp] is a name, not a path. Ansible resolves it against a search path, and the fastest way to see that path exactly is to ask for a role that does not exist:

Read-only / Safethe search path, read off a failure— Executed against ansible-core 2.21.3. The error message enumerates the search path in the order it was tried.

$ ansible-playbook -i inventory.ini missing.yml

[ERROR]: The role 'nonexistent_role' was not found in:
/srv/automation/roles:/home/deploy/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles:/srv/automation

Origin: /srv/automation/missing.yml:3:11

1 - hosts: local
2   gather_facts: false
3   roles: [nonexistent_role]
          ^ column 11

In order:

roles/ beside the playbook — /srv/automation/roles here. This is the project’s own roles directory and it wins.
roles_path — the configured list, three entries by default.
The playbook’s own directory — a fallback that occasionally surprises people who have a stray directory named like a role.

Collections come before all of this when you use a fully qualified name. namespace.collection.rolename bypasses the search path entirely and looks inside the installed collection, which is the unambiguous form and the one to prefer for anything you did not write.

Read-only / Safewhat roles_path is configured to— Reads the effective configuration. No connection to any host.

ansible-config dump | grep -i ROLES_PATH

Read-only / Safethe default, unmodified— Executed. The (default) marker means no ansible.cfg, environment variable or command-line option has changed it.

$ ansible-config dump | grep -i ROLES_PATH

DEFAULT_ROLES_PATH(default) = ['/home/deploy/.ansible/roles', '/usr/share/ansible/roles', '/etc/ansible/roles']

The shadowing failure

Two roles named nginx — one in the repository under roles/nginx, one installed into ~/.ansible/roles/nginx by a requirements.yml run months ago. The repository copy wins for you. On a colleague’s controller, where the repository copy was never added, the Galaxy copy wins. Same playbook, same inventory, same command, two different sets of tasks against production.

Nothing warns you. The name resolved; a role ran; the play succeeded.

Read-only / Safefind every role that shadows another— Lists role directory names from each search path location so duplicates are visible. Read-only.

for d in ./roles ~/.ansible/roles /usr/share/ansible/roles /etc/ansible/roles; do
[ -d "$d" ] || continue
for r in "$d"/*/; do
  [ -d "$r" ] && printf '%s\t%s\n' "$(basename "$r")" "$d"
done
done | sort | uniq -c | sort -rn | head -20

The operational habit that costs nothing: run --list-tasks before a real run and read the role prefixes. Every task inside a role is displayed as rolename : task name, so a role that resolved somewhere unexpected shows up as a task list you do not recognise.

Read-only / Saferole prefixes in --list-tasks— Executed. --list-tasks makes no connection and changes nothing; it prints the tasks the parser assembled.

$ ansible-playbook -i inventory.ini site.yml --list-tasks

playbook: site.yml

play #1 (web): configure the web tier	TAGS: []
  tasks:
    webapp : install packages	TAGS: []
    webapp : write configuration	TAGS: []
    webapp : start and enable the service	TAGS: []

Under the hood

Role loading happens at parse time, before any host is contacted. The role resolver walks the search path, and for each candidate directory checks whether it looks like a role — that is, whether it contains any of the recognised subdirectories.

This is why a typo in a role name fails before a single SSH connection is opened, and why the error message can enumerate the search path: nothing has happened yet except reading the controller’s own filesystem.

It is also why roles/webapp/tasks/main.yml being empty is not an error. An empty file parses as an empty task list. A role that does nothing is a valid role, and a role whose tasks you accidentally wrote into roles/webapp/task/ — singular — is a role that silently does nothing at all. The directory names are not validated against a list of known names; unrecognised directories are simply never read.

Search the tree rather than trusting your fingers:

find roles -maxdepth 2 -type d | sort

Anything that is not one of the recognised names is dead weight, and a near-miss like task/, handler/ or default/ is dead weight that looks correct in a code review.

What happens if a role and a collection role share a name?

The fully qualified name always wins for the thing it names. Writing community.general.example resolves inside that collection and never consults roles_path.

A bare example does the opposite: it never consults collections unless the play or the role declares a collections: search list, so a bare name is resolved from the filesystem search path.

The mixed case is where it bites. A play that lists both:

roles:
  - community.general.example    # from the collection
  - example                      # from ./roles or roles_path

runs two different roles that a reader will assume are the same one. If a role name in your repository collides with one you install from Galaxy, rename yours. A prefix — acme_example — costs one edit and removes an entire class of “it works on my controller” incident.

The directories

Where a bare role name is looked up

The shadowing failure

Knowledge check