Roles

Roles are the standard way to organise and share Ansible automation. A role packages tasks, variables, files, templates, and handlers into a reusable, self-contained unit with a well-defined directory structure.

---

Why Use Roles?

Benefit	Description
Reusability	Write once, use across multiple playbooks and projects
Organisation	Standard directory structure makes code easy to find and maintain
Sharing	Share roles via Ansible Galaxy or private repositories
Testing	Test roles independently with Molecule
Encapsulation	Each role has its own variables, defaults, files, and templates

---

Role Directory Structure

roles/
+-- nginx/
    +-- defaults/
    |   +-- main.yml       # Default variables (lowest precedence)
    +-- vars/
    |   +-- main.yml       # Role variables (higher precedence)
    +-- tasks/
    |   +-- main.yml       # Main task list
    +-- handlers/
    |   +-- main.yml       # Handler definitions
    +-- templates/
    |   +-- nginx.conf.j2  # Jinja2 templates
    +-- files/
    |   +-- index.html     # Static files
    +-- meta/
    |   +-- main.yml       # Role metadata and dependencies
    +-- tests/
    |   +-- test.yml       # Test playbook
    +-- README.md          # Documentation

Directory Purposes

Directory	Purpose
defaults/	Default variable values (easily overridden)
vars/	Role-specific variables (higher precedence than defaults)
tasks/	The main list of tasks to execute
handlers/	Handlers triggered by tasks in this role
templates/	Jinja2 template files (.j2)
files/	Static files to be copied to managed nodes
meta/	Role metadata: author, licence, dependencies, platforms
tests/	Test playbook for the role

Tip: You do not need to create all directories. Ansible only uses the directories that exist --- create only what you need.

---

Creating a Role

Using ansible-galaxy

# Create a role skeleton
ansible-galaxy role init roles/nginx

# This creates the full directory structure under roles/nginx/

Example: nginx Role

roles/nginx/defaults/main.yml:

nginx_port: 80
nginx_worker_processes: auto
nginx_worker_connections: 1024
nginx_server_name: "_"
nginx_root: /var/www/html

roles/nginx/tasks/main.yml:

---
- name: Install nginx
  apt:
    name: nginx
    state: present
    update_cache: true

- name: Deploy nginx configuration
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
  notify: Restart nginx

- name: Deploy site configuration
  template:
    src: default.conf.j2
    dest: /etc/nginx/sites-available/default
  notify: Reload nginx

- name: Ensure nginx is running
  service:
    name: nginx
    state: started
    enabled: true

roles/nginx/handlers/main.yml:

---
- name: Restart nginx
  service:
    name: nginx
    state: restarted

- name: Reload nginx
  service:
    name: nginx
    state: reloaded

---

Using Roles in Playbooks

roles Keyword

---
- name: Configure web servers
  hosts: webservers
  become: true