Ansible Fundamentals · Module 12 of 12

Roles & reuse

Organize proven automation into reusable roles and understand where collections fit as projects grow.

Learning objectives

By the end of this module, you should be able to:

Explain the standard role structure.
Create and invoke a simple role.
Distinguish a role from a collection and understand reuse boundaries.

Roles package related automation

As playbooks grow, roles provide a predictable structure for tasks, handlers, defaults, variables, templates and files. A role should represent a coherent responsibility such as configuring nginx or managing a baseline Linux service.

Defaults make roles reusable

Role defaults provide values that callers can override. This lets the role keep sensible behaviour while allowing controlled environment-specific variation without editing the role's tasks.

Collections distribute broader content

A collection can contain roles, modules, plugins and playbooks under a namespace. Collections are useful for distributing a larger body of automation. Beginners should first understand a local role, then learn how collections package and version reusable content.

Worked examples

See the idea in practice.

Create a role skeleton

mkdir -p roles
ansible-galaxy role init roles/webserver
find roles/webserver -maxdepth 2 -type f | sort

ansible-galaxy can create a conventional role structure.
You can remove unused directories later, but the standard layout helps other engineers navigate the role.

Use a role from a play

- name: Configure web tier
  hosts: web
  become: true
  roles:
    - role: webserver
      vars:
        webserver_port: 8080

The play assigns the role to the web group.
Role defaults can be overridden with environment-specific values.

Example role defaults

# roles/webserver/defaults/main.yml
webserver_package: nginx
webserver_service: nginx
webserver_port: 80

Defaults document configurable behaviour.
Tasks should consume variables instead of embedding every value.

Hands-on lab

Capstone — Turn the web playbook into a reusable role

Goal: Refactor the course's nginx automation into a role and apply it to the web inventory group.

STEP 1

Create role skeleton

ansible-galaxy role init roles/webserver

STEP 2

Move package and service tasks

Place the package, configuration/template and service logic into roles/webserver/tasks/main.yml.

STEP 3

Add defaults

# roles/webserver/defaults/main.yml
webserver_package: nginx
webserver_service: nginx
webserver_port: 80

STEP 4

Move restart handler

Put the restart handler in roles/webserver/handlers/main.yml and keep notify names consistent.

STEP 5

Run a small site playbook

ansible-playbook -i inventory.ini site.yml --syntax-check
ansible-playbook -i inventory.ini site.yml --check --limit web01
ansible-playbook -i inventory.ini site.yml --limit web01

STEP 6

Run again

ansible-playbook -i inventory.ini site.yml --limit web01

Verify

The role configures package, template and service state.
The handler triggers only when relevant configuration changes.
Role defaults can be overridden without editing role tasks.
A second run is normally clean.

Expected outcome

You finish with a reusable webserver role rather than a single long playbook.

If it fails

If role files are not found, check the project role path and role directory name.
If variables are undefined, inspect defaults/main.yml and variable scope.
If a handler does not run, verify task change status and notify spelling.

Real-world connection

Mature automation repositories use roles and collections to separate responsibilities, version reusable content and make review easier across teams.

Avoid these traps

Common mistakes

Creating one giant role that owns unrelated infrastructure responsibilities.
Putting environment-specific hard-coded values directly into reusable tasks.
Copying the same role into many repositories instead of versioning reusable content appropriately.

Knowledge check

Can you explain it without looking back?

Open each answer only after you have tried to answer the question yourself.

1What problem do roles solve?

They organize related reusable automation into a predictable structure.

2Why use role defaults?

They provide documented baseline values that callers can override without editing role logic.

3How is a collection broader than a role?

A collection can package multiple roles plus modules, plugins, playbooks and other Ansible content under a namespace.