Explaining Ansible Galaxy Roles

Ansible Galaxy is the official community repository where Ansible users can discover, share, install, and reuse automation content. One of its most popular features is roles, which are reusable collections of Ansible tasks, variables, templates, handlers, and files packaged using a standardized directory structure. Galaxy User Guide describes roles as pre-packaged automation units that help users avoid reinventing common configurations.

What Is an Ansible Role?

A role is a way to organize related automation into a reusable component.

Instead of creating a large playbook with hundreds of tasks, you can split functionality into roles:

nginx role
mysql role
docker role
monitoring role

Each role contains everything required for that specific function. Roles states that roles automatically load tasks, variables, handlers, templates, and files according to a known file structure.

Without Roles

---
- hosts: webservers
  become: yes

  tasks:
    - name: Install nginx
      apt:
        name: nginx
        state: present

    - name: Start nginx
      service:
        name: nginx
        state: started

With Roles

---
- hosts: webservers
  become: yes

  roles:
    - nginx

The role encapsulates all implementation details, making the playbook cleaner and easier to maintain.

Creating a Role

Use the ansible-galaxy command:

ansible-galaxy role init nginx

This generates a standard directory structure. ansible-galaxy documents the role init command for creating a role skeleton.

Generated Structure

nginx/
├── defaults/
│   └── main.yml
├── files/
├── handlers/
│   └── main.yml
├── meta/
│   └── main.yml
├── tasks/
│   └── main.yml
├── templates/
├── tests/
├── vars/
│   └── main.yml

This structure is the standard role layout recommended in Roles.

Understanding Each Folder

tasks/

Contains the automation tasks executed by the role.

tasks/main.yml

---
- name: Install Nginx
  apt:
    name: nginx
    state: present
`

handlers/

Contains handlers triggered only when changes occur.

handlers/main.yml

---
- name: restart nginx
  service:
    name: nginx
    state: restarted

templates/

Stores Jinja2 templates.

templates/nginx.conf.j2

server {
    listen {{ nginx_port }};
}

files/

Stores static files copied to target systems.

Example:

files/banner.txt

vars/

Contains high-priority variables.

nginx_version: latest

defaults/

Contains low-priority default values that users can override.

nginx_port: 80

meta/

Defines role metadata and dependencies.

dependencies:
  - role: common

These directories are part of the standard role model described in Roles.

Using a Role in a Playbook

Example:

---
- hosts: webservers
  become: yes

  roles:
    - nginx

When the playbook runs, Ansible automatically loads:

Tasks
Variables
Default values
Handlers
Templates

from the specified role.

Installing Roles from Ansible Galaxy

One of the biggest advantages of Galaxy is access to thousands of community-maintained roles. Galaxy User Guide explains that Galaxy provides reusable automation content contributed by the Ansible community.

Search for a Role

ansible-galaxy role search nginx

Install a Role

ansible-galaxy role install geerlingguy.nginx

The popular geerlingguy.nginx role installs and configures Nginx automatically. Role installation is documented in Galaxy User Guide. [docs.ansible.com]

Use the Installed Role

---
- hosts: webservers

  roles:
    - geerlingguy.nginx
``

Installing Multiple Roles

Create a file named requirements.yml.

roles:
  - src: geerlingguy.nginx
  - src: geerlingguy.mysql

Install all dependencies:

ansible-galaxy role install -r requirements.yml

Galaxy supports installing multiple roles through requirements files.

Role Dependencies

Roles can depend on other roles.

Example:

dependencies:
  - role: common
  - role: security
``

When the role executes, Ansible installs and runs the dependent roles automatically. This dependency mechanism is part of the role metadata system.

Galaxy Roles vs Collections

Historically, Galaxy focused on standalone roles. Modern Ansible increasingly uses Collections, which can contain:

Roles
Modules
Plugins
Playbooks
Documentation

Galaxy User Guide notes that collections are now the preferred packaging format because they provide a more comprehensive automation package.

Example:

ansible-galaxy collection install community.general

Best Practices

✅ Use Existing Roles

Before writing a new role, search Galaxy.

ansible-galaxy role search docker

✅ Keep Roles Focused

One role should perform one job.

Examples:

nginx
mysql
docker

✅ Use Defaults

Store customizable settings in:

defaults/main.yml

✅ Version Control Roles

Keep roles in Git repositories.

✅ Prefer Collections for New Projects

Collections are the modern packaging standard in Ansible.

Real-World Example

A web application deployment might look like:

---
- hosts: production

  roles:
    - common
    - docker
    - nginx
    - monitoring

Each role handles its own configuration, making the deployment modular, reusable, and easy to maintain.

Summary

Ansible Galaxy Roles are reusable automation components that package tasks, handlers, variables, templates, and files into a standardized structure. They allow teams to share automation, speed up deployments, improve code organization, and reduce duplication. While roles remain widely used, modern Ansible development increasingly packages roles inside Collections distributed through Ansible Galaxy

Tags: Ansible