Ansible Roles Explained

Analogy categoryAnalogies

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.

text

roles/
  nginx/
    tasks/
      main.yml
    handlers/
      main.yml
    templates/
      nginx.conf.j2
    files/
      robots.txt
    vars/
      main.yml
    defaults/
      main.yml
    meta/
      main.yml

Applying 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.