When working with Ansible, it’s important to follow best practices for structuring your roles. This ensures that your playbooks are maintainable, reusable, and easy to understand. Current stable version: Ansible-core 2.20.2 (released January 29, 2026). Here are the latest guidelines to help you achieve this:
Use a consistent directory structure for roles. A modern role directory might look like this:
my_role/
├── defaults/
│ └── main.yml
├── files/
│ └── ...
├── handlers/
│ └── main.yml
├── meta/
│ └── main.yml
├── tasks/
│ ├── main.yml
│ ├── install.yml
│ ├── config.yml
│ └── service.yml
├── templates/
│ └── ...
├── tests/
│ ├── test.yml
│ └── inventory
├── vars/
│ └── main.yml
├── .travis.yml
└── README.md
install.yml, config.yml, service.yml) and include them in main.yml.defaults for easily overridable values and vars for values that shouldn’t be changed.README.md file with role description, requirements, dependencies, variables, and usage examples.tests/ directory to validate role functionality across different environments.assert module to validate input variables and ensure role requirements are met.requirements.yml files.galaxy_info:
author: your name
description: your role description
company: your company (optional)
# If the issue tracker for your role is not on github, uncomment the
# next line and provide a value
# issue_tracker_url: http://example.com/issue/tracker
# Choose a valid license ID from https://spdx.org - some suggested licenses:
# - BSD-3-Clause (default)
# - MIT
# - GPL-2.0-or-later
# - GPL-3.0-only
# - Apache-2.0
# - CC-BY-4.0
license: license (GPL-2.0-or-later, MIT, etc)
min_ansible_version: 2.12
# If this a Container Enabled role, provide the minimum Ansible Container version.
# min_ansible_container_version:
#
# Provide a list of supported platforms, and for each platform a list of versions.
# If you don't wish to enumerate all versions for a particular platform, use 'all'.
# To view available platforms and versions (or releases), visit:
# https://galaxy.ansible.com/api/v1/platforms/
#
platforms:
- name: Ubuntu
versions:
- all
- name: EL
versions:
- "8"
- "9"
galaxy_tags: []
# List tags for your role here, one per line. A tag is a keyword that describes
# and categorizes the role. Users find roles by searching for tags. Be sure to
# remove the '[]' above, if you add tags to this list.
#
# NOTE: A tag is limited to a single word comprised of alphanumeric characters.
# Maximum 20 tags per role.
dependencies: []
# List your role dependencies here, one per line. Be sure to remove the '[]' above,
# if you add dependencies to this list.
By following these best practices, you can create Ansible roles that are robust, reusable, well-documented, and easy to maintain in modern DevOps environments.