Organizing Ansible Code with Roles

When working with complex Ansible projects, organizing your code becomes crucial for maintainability and scalability. Ansible roles provide a powerful way to structure your codebase and promote reusability. In this tutorial, we will explore how to organize Ansible code using roles.

Introduction to Organizing Ansible Code with Roles

Ansible roles allow you to encapsulate related tasks, variables, and templates into reusable units. They promote modularity and standardization, making it easier to manage and scale your Ansible projects. Roles enable you to structure your codebase in a logical and organized manner.

Let's take a look at a couple of examples:

Example 1: Creating a web server role

Suppose you want to provision multiple web servers with the same configuration. You can create a "web server" role that encapsulates the necessary tasks, variables, and templates specific to web server configuration. This role can then be reused across different playbooks or projects.

Example 2: Developing a database role

If you need to configure and manage databases across multiple hosts, you can create a "database" role. This role would contain tasks, variables, and templates related to database configuration, allowing you to easily apply consistent database configurations across your infrastructure.

Organizing Ansible Code with Roles

Here are the steps to organize Ansible code using roles:

Step 1: Create the Role Structure

Start by creating the basic structure of a role. A role typically consists of a directory with the same name as the role. Inside the role directory, you'll find subdirectories such as tasks/, vars/, templates/, and more, depending on your requirements.

Step 2: Define Tasks

In the tasks/ directory, define the tasks that need to be executed for the role. Tasks are written in YAML format and describe the actions to be performed on the target hosts. You can split tasks into multiple files for better organization.

Step 3: Manage Variables

In the vars/ directory, manage variables specific to the role. Variables can be defined in separate YAML files or within the main role file. Organize variables based on their purpose and use appropriate naming conventions to enhance readability.

Step 4: Use Templates

If your role requires generating configuration files or other text-based files, utilize the templates/ directory. Place Jinja2 template files in this directory, which can be populated with role-specific variables to create dynamic configurations.

Step 5: Include the Role in Playbooks

Incorporate the role in your Ansible playbooks using the roles: keyword. Specify the name of the role and the hosts to which the role should be applied. This allows you to reuse the role across different playbooks and easily apply it to specific hosts or groups.

Common Mistakes with Organizing Ansible Code with Roles

  • Creating roles that are too large and not focused on a specific task or functionality.
  • Not properly naming roles, leading to confusion and difficulty in identifying their purpose.
  • Forgetting to include necessary dependencies for a role, causing failures during playbook execution.
  • Not utilizing role variables effectively and hardcoding values within tasks or templates.
  • Overcomplicating role structure and organization, making it difficult to maintain and understand.

FAQs about Organizing Ansible Code with Roles

  1. Q: Can a role include other roles?

    A: Yes, a role can include other roles as dependencies. This allows you to create modular and reusable roles that can be easily composed together.

  2. Q: How can I reuse roles across different projects?

    A: To reuse roles, you can create an Ansible Galaxy collection or package the roles into a separate repository. This allows you to share and import the roles into different projects.

  3. Q: Can I override role variables?

    A: Yes, you can override role variables by defining them at different levels, such as in playbooks, inventory files, or command-line arguments. The most specific definition takes precedence.


Organizing Ansible code with roles brings structure and reusability to your automation projects. By following the steps outlined in this tutorial, you can create well-organized roles that encapsulate related tasks, variables, and templates. Leveraging roles simplifies the management and scalability of your Ansible codebase, promoting consistency and maintainability.