Playbook Organization

In the previous module, we covered AWX operations, details of job scheduling, REST API controls, and maintenance best practices. Organizing your configuration dashboard is the first step toward enterprise automation. However, to keep your code clean, readable, and portable, you must design a structured Git repository layout.

If developers store playbooks, roles, variable files, and inventories in a single flat directory, the workspace will quickly become difficult to navigate.

In this guide, we will cover the standard Ansible repository structure, analyze role groupings, and review best practices for file organization.

1. The Standard Repository Layout

A production-ready Ansible repository should follow a structured, multi-folder design. This separation of concerns ensures that host inventories, global variables, shared roles, and execution playbooks live in defined directories:

my-ansible-workspace/
├── site.yml                  # The main entry point playbook
├── webservers.yml            # Playbook targeting web servers
├── dbservers.yml             # Playbook targeting database servers
├── ansible.cfg               # Project-specific configuration options
├── requirements.yml          # External role and collection dependencies
├── inventories/
│   ├── production/
│   │   ├── hosts.ini         # Production inventory file
│   │   └── group_vars/       # Production group variables
│   │       ├── all.yml
│   │       └── webservers.yml
│   └── staging/
│       ├── hosts.ini         # Staging inventory file
│       └── group_vars/       # Staging group variables
│           ├── all.yml
│           └── webservers.yml
├── roles/
│   ├── common/               # Custom system role
│   └── webserver/            # Custom webserver role
└── group_vars/               # Global group variables (all environments)
    └── all.yml

2. Directory Layout Components Explained

The Entry Point (site.yml)

The master orchestrator playbook. It does not contain task definitions; instead, it imports environment playbooks:

# site.yml
---
- import_playbook: webservers.yml
- import_playbook: dbservers.yml

The inventories/ Directory

Contains separate folders for each lifecycle environment (e.g., staging, production). This structure ensures that staging and production variables are completely isolated, preventing developers from accidentally applying staging variables to production systems.

The group_vars/ and host_vars/ Directories

• Global group_vars/: Stored in the root directory. Contains variables that apply to all hosts across all environments (like default NTP servers or company DNS lookups).
• Environment-specific group_vars/: Stored inside the environment folder (e.g., inventories/production/group_vars/). Contains variables specific to that environment (like production database passwords or staging domain names).

3. Project Configuration with ansible.cfg

Configure your project to use your local directories automatically by defining parameters inside an ansible.cfg file stored in the root of your repository:

# ansible.cfg
[defaults]
# Search project-local folders first, falling back to system paths
roles_path = ./roles:./roles/vendor:~/.ansible/roles
collections_path = ./collections:~/.ansible/collections

# Set the default inventory path
inventory = ./inventories/staging/hosts.ini

# Optimize performance settings
pipelining = True
forks = 20

4. Operational Best Practices: Repository Layout

• Keep playbooks dedicated to single concerns: Avoid creating massive monolithic playbook files containing multiple unrelated hosts. Keep your playbooks focused on specific roles.
• Pin external dependencies: Store all community roles inside a requirements.yml file and download them to ./roles/vendor/ to separate them from your custom roles.
• Keep directories clean: Add temporary execution logs or local credential files to your .gitignore file.

5. Directory Layout Components Reference Summary

Now that we have covered how to structure your Ansible workspace directory layout, the next step is establishing naming rules. In the next section, we will cover how to design clear naming conventions for tasks, plays, and variables.