Chapter 8: Simplifying Playbooks with Roles and Collections

Ansible roles and collections cheat sheet

The chapter on one page: the role layout, the commands for roles and collections, and flashcards for quick revision.

The chapter in six sentences

A role packages tasks with their variables, templates, files and handlers in a standard directory layout, so the work can be reused and shared.
A play runs pre_tasks, roles, tasks, post_tasks, in that order, with pending handlers run between the stages.
Settings a user may change go in defaults/main.yml; values in vars/main.yml are internal and outrank inventory and play variables.
ansible-galaxy role init creates a role skeleton; ansible-galaxy role install -r roles/requirements.yml -p roles installs roles from Git repositories, archives or Galaxy, and roles_path = roles saves the -p.
System roles configure common services through variables and are used by their collection name, such as redhat.rhel_system_roles.timesync; the selinux role reports a needed reboot by failing, which a rescue section handles.
A collection is a versioned package of modules, roles and plug-ins, named namespace.collection, installed with ansible-galaxy collection install and found through collections_path.

Cheat sheet

Role layout

roles/web_site/
├── defaults/main.yml     settings, lowest precedence: meant to be overridden
├── vars/main.yml         internal values, high precedence
├── tasks/main.yml        the tasks (the only required file)
├── handlers/main.yml     handlers the tasks notify
├── templates/            Jinja2 templates, found by file name
├── files/                static files, found by file name
└── meta/main.yml         author, licence, dependencies

Using roles

- name: Web servers
  hosts: web
  pre_tasks:                      # 1
    - ansible.builtin.debug: { msg: before }
  roles:                          # 2
    - role: web_site
      vars:
        web_site_title: Staff intranet
    - redhat.rhel_system_roles.timesync
  tasks:                          # 3
    - name: A role, as a task
      ansible.builtin.include_role:
        name: monitoring
      when: monitor | bool
  post_tasks:                     # 4
    - ansible.builtin.debug: { msg: after }

Role commands

ansible-galaxy role init roles/web_site
ansible-galaxy role install -r roles/requirements.yml -p roles
ansible-galaxy role list -p roles
ansible-galaxy role remove -p roles acme.banner
ls /usr/share/doc/rhel-system-roles/          # system role READMEs and examples

# roles/requirements.yml
- src: https://git.example.com/ops/ansible-role-banner.git
  scm: git
  version: v1.2
  name: acme.banner
- src: file:///home/student/project/archives/acme.motd-1.0.tar.gz
  name: acme.motd

Collections

ansible-galaxy collection list
ansible-galaxy collection install community.crypto:2.26.0 -p collections
ansible-galaxy collection install -r collections/requirements.yml -p collections
ansible-navigator doc community.crypto.openssl_privatekey -m stdout

# collections/requirements.yml
collections:
  - name: community.crypto
    version: 2.26.0

# ansible.cfg
[defaults]
collections_path = ./collections:~/.ansible/collections:/usr/share/ansible/collections

A variable set in	Beats
Role `defaults/main.yml`	Nothing
Inventory (`group_vars`, `host_vars`)	Role defaults
Play `vars`	Inventory
`vars:` on the role entry	Play `vars`
Role `vars/main.yml`	All of the above
Inline role parameter	Role `vars`
`-e` on the command line	Everything

Where do a role’s tasks normally start?: `tasks/main.yml`. No individual file is mandatory for every kind of role.
Where do user-changeable role settings go?: `defaults/main.yml`: lowest precedence, so anything overrides them.
What is special about `vars/main.yml` in a role?: High precedence: inventory and play variables do **not** override it.
In what order does a play run its sections?: `pre_tasks` → roles → `tasks` → `post_tasks`, with handlers flushed between stages.
How do you create a role skeleton?: `ansible-galaxy role init roles/NAME`
How do you run a role from the task list, conditionally?: `ansible.builtin.include_role` with `name:` and a `when`.
What does `dependencies` in `meta/main.yml` do?: Runs the listed roles **before** this role, automatically.
Full name of the timesync system role?: `redhat.rhel_system_roles.timesync`
Where are system role docs and examples?: `/usr/share/doc/rhel-system-roles/ROLE/`
Install all roles a project needs?: `ansible-galaxy role install -r roles/requirements.yml -p roles`
The three parts of an FQCN?: `namespace.collection.name`, for example `ansible.posix.firewalld`.
"couldn’t resolve module/action": where is the problem?: On the **control node**: collection missing, misspelt, or not on `collections_path`.