Organizing your playbooks into roles helps you manage automation tasks in a more reusable and maintainable way. Roles allow you to group related files, variables, and tasks together, making it easier to share and update your automation code. By structuring your playbooks with roles, you can:

• Separate concerns by dividing tasks into logical units;
• Reuse common configurations across different projects;
• Simplify updates and troubleshooting by keeping related files together;
• Make your automation code easier for others to understand and contribute to.

Using roles is a best practice that helps you build scalable and reliable automation with Ansible.

Role Folder Structure

A typical Ansible role has a specific folder structure that helps you organize automation content. Here is what a basic role directory looks like:

my_role/
├── tasks/
├── handlers/
├── vars/
├── templates/
└── files/

tasks

• Contains the main list of tasks the role executes;
• Each task is a step in your automation, such as installing packages or editing configuration files;
• The main task file is usually named main.yml.

handlers

• Contains handlers, which are special tasks triggered by other tasks;
• Handlers typically perform actions like restarting a service only when notified by a task;
• The main handler file is usually named main.yml.

vars

• Stores variables that the role uses;
• Variables can define values such as usernames, paths, or ports;
• The main variable file is usually named main.yml.

templates

• Contains Jinja2 template files, which are configuration files with placeholders for variables;
• Templates let you generate dynamic files based on your environment;
• Files in this directory use the .j2 extension, such as nginx.conf.j2.

files

• Stores static files that the role copies directly to managed hosts;
• Use this directory for files that do not need variable substitution, such as certificates or scripts;
• Files are referenced in tasks and transferred as-is.

This structure keeps your roles organized, reusable, and easy to understand.

Including a Role in a Playbook

To use a role in your Ansible playbook, add the roles keyword under a play's tasks. This tells Ansible to apply all the tasks, handlers, variables, and files defined in that role.

Here is a basic example of a playbook that includes a role named webserver:

- name: Configure web servers
  hosts: web
  become: true
  roles:
    - webserver

In this example:

• The play runs on all hosts in the web group;
• Privilege escalation is enabled with become: true;
• The webserver role is applied, which automatically runs all of its tasks and handlers.

This structure keeps your playbooks organized and makes it easy to reuse configuration logic across multiple projects.

Best Practices: Using Roles for Readable and Shareable Playbooks

Follow these best practices to make your Ansible playbooks easier to read and share by organizing them with roles:

• Group related tasks, handlers, variables, and files into a single role;
• Use clear, descriptive names for roles, such as web_server or database_backup;
• Keep each role focused on a specific function to avoid confusion;
• Place reusable code in roles to reduce duplication in your playbooks;
• Share roles with teammates by storing them in a shared repository or using Ansible Galaxy.

Organizing your playbooks with roles helps others quickly understand your automation, reuse your work, and maintain consistency across projects.