Ansible Project Structure

A tidy project saves hours of searching and prevents costly mistakes. Ansible does not force a folder layout, yet the community follows proven patterns. Think of a well organized toolbox: hammers in one drawer, screws in another, and a label on every drawer. A clear structure lets a new teammate find any file within seconds.

Recommended Layout

shop-automation/
├── ansible.cfg
├── requirements.yml
├── site.yml
├── webservers.yml
├── dbservers.yml
├── inventories/
│   ├── production/
│   │   ├── hosts.ini
│   │   ├── group_vars/
│   │   │   ├── all.yml
│   │   │   └── webservers.yml
│   │   └── host_vars/
│   │       └── web1.yml
│   └── staging/
│       ├── hosts.ini
│       └── group_vars/
│           └── all.yml
├── roles/
│   ├── common/
│   ├── nginx/
│   └── mariadb/
├── collections/
├── library/
├── files/
└── templates/

Diagram: How the Pieces Connect

  ┌────────────┐   imports   ┌────────────────┐
  │  site.yml  │────────────▶│ webservers.yml │
  └─────┬──────┘             └───────┬────────┘
        │                            │ calls
        │ imports                    ▼
        ▼                     ┌────────────┐
  ┌────────────────┐          │   roles/   │
  │  dbservers.yml │─────────▶│ common     │
  └────────────────┘  calls   │ nginx      │
                              │ mariadb    │
                              └─────┬──────┘
                                    │ reads values from
                                    ▼
                         ┌────────────────────┐
                         │ inventories/       │
                         │   production or    │
                         │   staging          │
                         └────────────────────┘

Separate Inventories per Environment

Give production and staging their own inventory folders. The same playbooks run against either environment with one flag.

ansible-playbook -i inventories/staging/hosts.ini site.yml
ansible-playbook -i inventories/production/hosts.ini site.yml

Variables that differ per environment, such as database addresses and port numbers, live in each environment's group_vars. Playbooks and roles stay identical.

A Master Playbook

# site.yml
- import_playbook: webservers.yml
- import_playbook: dbservers.yml
# webservers.yml
- name: Configure web servers
  hosts: webservers
  become: true
  roles:
    - common
    - nginx

Keep playbooks short. They read like a table of contents, and roles hold the real work.

Role Design Rules

  • Give each role one clear purpose
  • Place tunable values in defaults/main.yml with a role name prefix
  • Document every variable in the role README.md
  • Avoid hard coded host names inside roles

Naming Conventions

ItemConventionGood Example
Task nameStarts with an action verbInstall nginx package
VariableLowercase with underscores and role prefixnginx_worker_count
RoleShort nounnginx
HandlerDescribes the effectReload nginx
TagLowercase wordconfig

Version Control Habits

  • Commit the whole project to Git and use branches for changes
  • Add a .gitignore entry for vault password files, *.retry, and temporary folders
  • Encrypt secret values with Ansible Vault before committing
  • Require a review for changes that touch production inventories

Pin Dependencies

A requirements.yml file lists roles and collections with exact versions. Run ansible-galaxy install -r requirements.yml on any machine to rebuild the same setup.

collections:
  - name: community.general
    version: 8.3.0
roles:
  - name: geerlingguy.docker
    version: 7.0.0

Check the Quality

ansible-playbook site.yml --syntax-check
ansible-lint site.yml
ansible-playbook site.yml --check --diff

Try This

Build the folder skeleton from the layout above using mkdir -p. Create two inventories that each set a variable named app_env. Write a playbook that prints the variable. Run it against both inventories and confirm each run prints its own value.

Summary

A consistent folder layout makes Ansible projects readable and safe. Separate inventories isolate environments, short playbooks act as tables of contents, and focused roles hold reusable logic. Naming rules, version control, pinned dependencies, and automated checks keep quality high as the project grows.