What a Role Actually Is
An Ansible role is a self-contained, structured bundle of tasks, handlers, variables, templates, and files that together automate one piece of functionality, such as installing and configuring Nginx. Instead of writing one enormous playbook with hundreds of tasks, you split the work into roles, and a playbook simply lists which roles to apply to which hosts. This separation turns automation into composable building blocks rather than a monolithic script.
Cricket analogy: Think of a role like a specialist player brought into an XI for a specific job — a death-overs bowler like Jasprit Bumrah is not asked to open the batting; the team composes specialists rather than relying on one player to do everything.
The Standard Directory Layout
Ansible expects roles to follow a fixed directory structure so that tooling can auto-discover content without extra configuration: tasks/main.yml holds the task list, handlers/main.yml holds notify targets, templates/ holds Jinja2 files, files/ holds static files to copy, vars/main.yml and defaults/main.yml hold variables (with defaults/ being the lowest-precedence, easily overridden layer), and meta/main.yml declares role metadata and dependencies. Because ansible-galaxy init generates this skeleton automatically, and ansible-playbook looks for these exact filenames, sticking to the convention means you rarely need to write explicit include paths.
Cricket analogy: It's like the fixed batting order slots a team files before a match — opener, number three, middle order, finisher — where everyone knows what's expected in each slot without needing a separate memo, the way MS Dhoni was always the designated finisher.
roles/
nginx/
tasks/
main.yml
handlers/
main.yml
templates/
nginx.conf.j2
files/
robots.txt
vars/
main.yml
defaults/
main.yml
meta/
main.ymlApplying Roles in a Playbook
A playbook consumes roles either through the classic roles: list, which runs before any tasks: block on that play, or through the more flexible import_role / include_role module calls placed anywhere in the tasks sequence, letting you interleave role logic with ad-hoc tasks and pass per-invocation variables. import_role is processed at playbook parse time (static), while include_role is resolved at runtime (dynamic), which matters if you need conditionals or loops around the role call.
Cricket analogy: Choosing roles: versus include_role is like deciding the batting order before the toss versus a captain making a live substitution mid-innings when conditions change — one is fixed upfront, the other reacts dynamically.
Prefer roles: for the common case of applying a fixed set of roles to a play, and reach for include_role only when you need runtime conditionals, loops, or dynamic variable-driven role names.
Variable Precedence Inside Roles
Variables set in defaults/main.yml have the lowest precedence in Ansible's variable resolution order, which is exactly why they belong there: they act as sane, easily overridden fallbacks. Variables in vars/main.yml sit much higher in precedence and are harder to override from a playbook or inventory, so they should hold values the role genuinely needs to remain correct, such as internal file paths, not user-tunable settings like a port number.
Cricket analogy: It's like a franchise's default squad list going into an auction — easily reshuffled — versus the fixed rule that a team must field exactly eleven players, which no owner can override.
Setting a value in vars/main.yml instead of defaults/main.yml is a common mistake that quietly makes a role harder to customize, because callers must resort to extra-vars or explicit playbook-level overrides to change it.
- A role packages tasks, handlers, templates, files, and variables into one reusable unit of automation.
- The fixed directory layout (tasks/, handlers/, templates/, files/, vars/, defaults/, meta/) is auto-discovered by Ansible without extra configuration.
- roles: in a playbook runs statically before tasks:; import_role is static, include_role is dynamic and supports conditionals/loops.
- defaults/main.yml holds low-precedence, easily overridden fallback variables meant for user tuning.
- vars/main.yml holds high-precedence variables that represent the role's own fixed requirements, not user-tunable settings.
- ansible-galaxy init scaffolds the standard role skeleton automatically.
- Splitting playbooks into roles turns automation into composable, testable, shareable building blocks.
Practice what you learned
1. Which file within a role holds the main list of tasks Ansible executes?
2. Why should tunable configuration values live in defaults/main.yml rather than vars/main.yml?
3. What is the key difference between import_role and include_role?
4. Which command scaffolds the standard role directory structure automatically?
Was this page helpful?
You May Also Like
Ansible Galaxy and Collections
Understand Ansible Galaxy as a content hub and Collections as the modern packaging format for roles, modules, and plugins.
Role Dependencies
Learn how to declare dependencies between Ansible roles using meta/main.yml, and understand ordering, deduplication, and pitfalls.
Reusable Role Design
Practical principles for writing Ansible roles that are genuinely reusable across projects, teams, and environments.
Testing Roles with Molecule
Learn how Molecule automates spinning up test instances, converging a role, and verifying results to give roles real automated tests.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics