Ansible Roles: Basics, Creating & Using

This blog post explores the concept of Ansible roles, their structure, and how we can combine them with our playbooks. We will analyze their functionality and usage along with ways to create new roles and retrieve public shared roles from Ansible Galaxy, a public repository for Ansible resources.

If you are new to Ansible, you might also find these tutorials helpful Ansible Tutorial for Beginners, Working with Ansible Playbooks, and How to Use Different Types of Ansible Variables.

Ansible Roles provide a well-defined framework and structure for setting your tasks, variables, handlers, metadata, templates, and other files. They enable us to reuse and share our Ansible code efficiently. This way, we can reference and call them in our playbooks with just a few lines of code while we can reuse the same roles over many projects without the need to duplicate our code.

When starting with Ansible, it’s pretty common to focus on writing playbooks to automate repeating tasks quickly. As new users automate more and more tasks with playbooks and their Ansible skills mature, they reach a point where using just Ansible playbooks is limiting. Ansible Roles to the rescue!

Since we have our code grouped and structured according to the Ansible standards, it is quite straightforward to share it with others. We will see an example of how we can accomplish that later with Ansible Galaxy. 

Organizing our Ansible content into roles provides us with a structure that is more manageable than just using playbooks. This might not be evident in minimal projects but as the number of playbooks grows, so does the complexity of our projects. 

Lastly, placing our Ansible code into roles lets us organize our automation projects into logical groupings and follow the separation of concerns design principle. Collaboration and velocity are also improved since different users can work on separate roles in parallel without modifying the same playbooks simultaneously.

Let’s have a look at the standard role directory structure. For each role, we define a directory with the same name. Inside, files are grouped into subdirectories according to their function. A role must include at least one of these standard directories and can omit any that isn’t actively used.

To assist us with quickly creating a well-defined role directory structure skeleton, we can leverage the command ansible-galaxy init <your_role_name>. The ansible-galaxy command comes bundled with Ansible, so there is no need to install extra packages.

Create a skeleton structure for a role named test_role:

This command generates this directory structure:

Ansible checks for main.yml files, possible variations, and relevant content in each subdirectory. It’s possible to include additional YAML files in some directories. For instance, you can group your tasks in separate YAML files according to some characteristic.

• defaults –  Includes default values for variables of the role. Here we define some sane default variables, but they have the lowest priority and are usually overridden by other methods to customize the role.
• files  – Contains static and custom files that the role uses to perform various tasks.
• handlers – A set of handlers that are triggered by tasks of the role. 
• meta – Includes metadata information for the role, its dependencies, the author, license, available platform, etc.
• tasks – A list of tasks to be executed by the role. This part could be considered similar to the task section of a playbook.
• templates – Contains Jinja2 template files used by tasks of the role. (Read more about how to create an Ansible template.)
• tests – Includes configuration files related to role testing.
• vars – Contains variables defined for the role. These have quite a high precedence in Ansible.

Another directory that wasn’t automatically generated by the ansible-galaxy init command but is mentioned in the official Ansible docs, and you might find helpful in some cases, is the library directory. Inside it, we define any custom modules and plugins that we have written and used by the role. Finally, we also have a preconfigured README.md file that we can fill with details and useful information about our role.

A common tactic is to refactor an Ansible playbook into a role. To achieve that, we have to decompose the different parts of a playbook and stitch them together into an Ansible role using the directories we’ve just seen in the previous section. 

This section will go through an example of creating a new role for installing and configuring a minimal Nginx web server from scratch. If you wish to follow along, you will need VirtualBox, Ansible, and Vagrant installed locally.

Ansible searches for referenced roles in common paths like the orchestrating playbook’s directory, the roles/ directory, or the configured roles_path configuration value. It’s also possible to set a custom path when referencing a role:

Using the ansible-galaxy init command, we generate the initial directory structure for a role named webserver inside a parent directory named roles. Let’s go ahead and delete the tests directory since we won’t be using it. We will see how to utilize all the other directories during our demo. 

The final structure of our role looks like this:

First, let’s define the most fundamental part of our role, its tasks. Head to the tasks directory and edit the main.yml file.

roles/webserver/tasks/main.yml

Here, we define a handful of tasks that update the operating system, install an Nginx web server, and set up a minimal custom configuration for demo purposes.

Next, we move to the defaults directory, where we will set default values for the variables used in the tasks. If there is no other definition for these variables, they will be picked up and used by the role, but usually, they are meant to be easily overwritten.

roles/webserver/defaults/main.yml

Moving on to our vars directory, we define values with higher precedence that aren’t meant to be overridden at the play level. Here, we override the default variable that defines the Nginx custom directory.

roles/webserver/vars/main.yml

In the handlers directory, we define any handler that is triggered by our tasks. One of our tasks includes a notify keyword since it needs to trigger our Restart the Nginx service handler.

roles/webserver/handlers/main.yml

In the templates directory, we leverage a Jinja2 template file for the Nginx configuration that gets the Nginx custom directory value from one of our previously defined variables.

roles/webserver/templates/nginx.conf.j2

In the files directory, we define a static file index.html that will serve as our static demo webpage.

roles/webserver/files/index.html

We use the meta directory to add metadata and information about the role. Any role dependencies by other roles go here as well.

roles/webservers/meta/main.yml

Lastly, we update the README.md file accordingly. The autogenerated file provided by the ansible-galaxy init command includes many pointers and guidance on filling this nicely. 

roles/webserver/README.md

Once we have defined all the necessary parts of our role, it’s time to use it in plays. The classic and most obvious way is to reference a role at the play level with the roles option:

With this option, each role defined in our playbook is executed before any other tasks defined in the play.

This is an example play to try out our new webserver role. Let’s go ahead and execute this play. To follow along, you should first run the vagrant up command from the top directory of this repository to create our target remote host.

Sweet! All the tasks have been completed successfully. Let’s also validate that we have configured our Ngnix web server correctly.

Use the command vagrant ssh host1 to connect to our demo Vagrant host. Then execute systemctl status nginx to verify that Nginx service is up and running. Finally, run the command curl localhost to check if the web server responds with the custom page that we configured.

When using the roles option at the play level, we can override any of the default role’s variables or pass other keywords, like tags. Ansible tags are added to all tasks within the role.

Here, we override the default variable nginx_version with another version.

Apart from defining roles at the play level with the roles option, we can use them also at the tasks level with the options include_role dynamically and import_role statically. These are useful when we would like to run our role tasks in a specific order and not necessarily before any other playbook tasks. This way, roles run in the order they are defined in plays.

Check the official docs for achieving more fine-grained control of your role’s task execution order. 

Even if we define a role multiple times, Ansible will execute it only once. Occasionally, we might want to run a role multiple times but with different parameters. Passing a different set of parameters to the same roles allows executing the role more than once. 

Example of executing the role test three times:

Ansible Galaxy is an online open-source, public repository of Ansible content. There, we can search, download and use any shared roles and leverage the power of its community. We have already used its client, ansible-galaxy, which comes bundled with Ansible and provides a framework for creating well-structured roles.

You can use Ansible Galaxy to browse for roles that fit your use case and save time by using them instead of writing everything from scratch. For each role, you can see its code repository, documentation, and even a rating from other users. Before running any role, check its code repository to ensure it’s safe and does what you expect. Here’s a blog post on How to evaluate community Ansible roles. If you are curious about Galaxy, check out its official documentation page for more details.

To download and install a role from Galaxy, use the ansible-galaxy install command. You can usually find the installation command necessary for the role on Galaxy. For example, look at this role that installs a PostgreSQL server.

Install the role with:

Then use it in a playbook while overriding the default role variable postgresql_users to create an example user for us.

This section gathers some tips and tricks that might help you along your journey with Ansible roles.

• Always use descriptive names for your roles, tasks, and variables. Document the intent and the purpose of your roles thoroughly and point out any variables that the user has to set. Set sane defaults and simplify your roles as much as possible to allow users to get onboarded quickly.
• Never place secrets and sensitive data in your roles YAML files. Secret values should be passed to the role at execution time by the play as a variable and should never be stored in any code repository.
• At first, it might be tempting to define a role that handles many responsibilities. For instance, we could create a role that installs multiple components, a common anti-pattern. Try to follow the separation of concerns design principle as much as possible and separate your roles based on different functionalities or technical components.
• Try to keep your roles as loosely coupled as possible and avoid adding too many dependencies. 
• To control the execution order of roles and tasks, use the import_role or Include_role tasks instead of the classic roles keyword.
• When it makes sense, group your tasks in separate task files for improved clarity and organization.

To learn more, check out the 44 Ansible Best Practices to Follow.

Spacelift’s vibrant ecosystem and excellent GitOps flow can greatly assist you in managing and orchestrating Ansible. By introducing Spacelift on top of Ansible, you can then easily create custom workflows based on pull requests and apply any necessary compliance checks for your organization.

Another great advantage of using Spacelift is that you can manage different infrastructure tools like Ansible, Terraform, Pulumi, AWS CloudFormation, and even Kubernetes from the same place and combine their Stacks with building workflows across tools.

Our latest Ansible enhancements solve three of the biggest challenges engineers face when they are using Ansible:

• Having a centralized place in which you can run your playbooks
• Combining IaC with configuration management to create a single workflow
• Getting insights into what ran and where

Provisioning, configuring, governing, and even orchestrating your containers can be performed with a single workflow, separating the elements into smaller chunks to identify issues more easily.

Would you like to see this in action – or just want a tl;dr? Check out this video I put together showing you Spacelift’s new Ansible functionality:

If you want to learn more about using Spacelift with Ansible, check our documentation, read our Ansible guide, or book a demo with one of our engineers.

We deep-dived into Ansible Roles and their utility and saw how to refactor our playbooks into roles or generate them from scratch. We went through a complete example of creating and using a role and explored how we can benefit from the Ansible Galaxy community.

Thank you for reading, and I hope you enjoyed this “Ansible Roles” blog post as much as I did.