Ansible roles directory structure overview | Beginners Guide

In this article I will give you an overview on Ansible Roles directory structure. When working with Ansible it is recommended to use project directories so that contents can be organised in a consistent way. Each project directory may have its own ansible.cfg, inventory as well as playbooks. Roles can be used to standardise and easily re-use specific parts of Ansible

Before we start with our Ansible Roles Directory Structure Tutorial, you must be familiar with the below topics:

What are Ansible roles?

Ansible playbooks can be very similar: code used in one playbook can be useful in other playbooks also
To make it easy to re-use the code, roles can be used.
An Ansible role is composed of multiple folders, each of which contain several YAML files.
By default, they have a main.yml file, but they can have more than one when needed.
This is a standardized structure for all Ansible roles, which allows Ansible playbooks to automatically load predefined variables, tasks, handlers, templates, and default values located in separate YAML files.
Each Ansible role should contain at least one of the following directories, if not all of them.

Understanding ansible roles directory structure

I have create a new role "roles". Below is the ansible roles directory structure for roles directory.

roles
├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── README.md
├── tasks
│   └── main.yml
├── templates
├── tests
│   ├── inventory
│   └── test.yml
└── vars
    └── main.yml

Now we will understand the individual directory in this ansible roles directory structure. Each directory in this structure serves a different purpose which we will discuss below

The defaults folder

defaults/main.yml is a configuration file that you can use to define default values for variables used in your role.
It allows for a centralized management of the default values of the variable of the role.
Default values are always vulnerable because they change a lot depending on the needs and policies of the user.
Having this solution allows one file to change all the values

The files folder

This folder holds all extra files that are required to achieve the role task.
These files usually get dispatched to remote hosts as part of certain tasks.
They are usually static, and they do not contain any variables to change, be copied, extracted, or compressed to the remote host.

The handlers folder

handlers/main.yml is where you will define handlers like restart nginx.
It is mainly used for service management to apply a configuration change performed by another task.
Handlers can be called in the same role, from other roles, and from the calling playbook.

The meta folder

meta/main.yml is the metadata file for your role.
These folders contain the role metadata, which includes information about authors, licenses, compatibilities, and dependencies.
The main use for this option is to declare dependencies, more specifically, roles.
If the current role relies on another role, that gets declared in a meta folder.

The tasks folder

tasks/main.yml is where you’ll spend most of your time.
It contains the main YAML files.
The code within those files executes the main role tasks by calling all the other defined elements of the role.
Any actions defined in this file will be executed by Ansible when your role runs.

The templates folder

This folder contains the template files used by the role to create the actual configuration files.
These are then deployed by the role to the remote hosts.
They are Jinja2 template engine scripts that enable loops and other features.

The tests folder

This folder contains a test environment with an inventory file and a playbook script to test the role.
This is primarily used when testing your role automatically using a continuous integration system, such as Jenkins or Travis CI
Although eight folders were just discussed, not all of them are mandatory. Your role can be very useful, even if you only provide a tasks file. Most of the time, you’ll find that you’re working in the tasks folder, with supporting files found in handlers and templates.

The vars folder

This is where the role variables get stored.
Usually, it is used for a permanent variable that does not require any changes between environments.

How variables should be defined in a role?

Variables can be defined at different levels in the ansible roles directory structure.
main.yml inside vars folder has the default variables, which are used in default role functioning. They are not intended to be overwritten
defaults/main.yml can contain default variables. These have a low precedence and can be overwritten by variables with the same name that are set in the playback and which have higher precedence
Playbook variables will always overwrite the variables as set in the role. Site-specific variables such as secrets and vault encrypted data should always be managed from the playbook as role variables are intended to be generic
Role variables are defined in the playbook when calling the role and they have the highest precedence and overwrite playbook variables as well as inventory variables

Different location for Ansible roles

Roles can be stored at default location and from there can be easily used from playbooks

./roles has the highest precedence
~/.ansible/roles is checked after that
/etc/ansible/roles is checked next

What's Next

Now that we are familiar with roles structure, next in our Ansible Tutorial we will create our first Ansible role to perform some tasks using playbook

References:
Ansible quick start quide