Ansible roles directory structure overview | Beginners Guide

Written by - Deepak Prasad

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.

├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── 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


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


Ansible quick start quide

Deepak Prasad

He is the founder of GoLinuxCloud and brings over a decade of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive experience, he excels in various domains, from development to DevOps, Networking, and Security, ensuring robust and efficient solutions for diverse projects. You can reach out to him on his LinkedIn profile or join on Facebook page.

Can't find what you're searching for? Let us assist you.

Enter your query below, and we'll provide instant results tailored to your needs.

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can send mail to

Thank You for your support!!

Leave a Comment