Chapter 8: Simplifying Playbooks with Roles and Collections

Describing role structure

Task files let you reuse a list of tasks. A role goes further: it bundles tasks with the variables, templates, files and handlers they need, in a standard layout that Ansible understands. A well-made role can be dropped into any project and used with one line.

• Explain what a role is and why roles make playbooks easier to maintain.
• Name the directories of a role and what belongs in each.
• Use a role in a play, and predict the order in which roles, tasks and handlers run.
• Predict which value a role variable gets when it is set in several places.

What a role is

A role is a directory with a fixed structure. Each subdirectory has one job, and Ansible loads main.yml from each automatically. Because the layout is always the same, anyone who has seen one role can find their way around another.

Roles pay off in three ways:

• Reuse. Write "set up a web server" once; use it in every project that needs one.
• Sharing. A role is a self-contained folder, so it can be handed to a colleague, stored in its own repository, or published.
• Shorter playbooks. A play that uses roles reads like a summary: which hosts, which roles.

The role layout

Select a file to see what it is for:

No individual file is mandatory: a role may provide tasks, variables, handlers, or files. A role that runs tasks normally uses tasks/main.yml. Leave out, or delete, any directory a role does not use.

Inside a role, template and copy tasks refer to their source by file name alone. Ansible looks in the role's own templates/ and files/ directories first.

Using a role in a play

List roles under the roles keyword of a play:

- name: Web servers run the site
  hosts: web
  roles:
    - web_site
    - monitoring_agent

Ansible looks for each role in a roles/ directory next to the playbook, then in the directories of the roles_path setting (by default ~/.ansible/roles, /usr/share/ansible/roles and /etc/ansible/roles).

To set a role's variables for one play, give the role entry a vars section:

  roles:
    - role: web_site
      vars:
        web_site_title: Staff intranet

The order things run in

A play can contain roles and its own tasks. Ansible does not run them in the order they are written. It runs pre_tasks, then roles, then tasks, then post_tasks, with handler flushes after pre_tasks, after roles and tasks together, and after post_tasks. Select a step to see where it comes from:

Use pre_tasks for something that must happen before any role, such as taking a host out of a load balancer, and post_tasks for the matching step afterwards.

Variables in a role

A role has two places for variables, and they behave very differently:

The role's settings, with sensible starting values. They have the lowest precedence of anything in Ansible, so inventory, play variables and the command line can all override them.

Values the role needs internally, such as a path that must not change. They have high precedence: inventory and play variables do not override them.

Tick the places where a variable is set and see which value the role ends up with:

• Which file normally contains the tasks that a role runs?
• A play has `tasks`, `roles` and `pre_tasks`, written in that order. What runs first?
• Where should a role keep a setting that users are expected to change?
• A role sets `web_site_title` in `vars/main.yml`. The play sets it too, under `vars:`. Which value is used?
• A role task has `src: site.conf.j2` with no path. Where does Ansible look first?

Takeaway

Explain what a role is and why roles make playbooks easier to maintain. Use the chapter lab to check this on a real host.