The Recommended Directory Layout

As projects grow, scattered files become chaos. A standard directory layout tells your team exactly where everything lives. 📁

By convention, site.yml is the top-level playbook that ties your whole infrastructure together and includes the rest.

Your inventory file (or directory) sits near the top, so the playbooks beside it always know which hosts they manage.

Split big plays into focused files like webservers.yml and dbservers.yml, then stitch them together from site.yml.

A group_vars directory holds variables that apply to whole host groups, loaded automatically by group name.

The host_vars directory does the same for single machines, with one file named after each individual host.

Reusable automation lives under a roles directory. Ansible looks here first when a play references a role by name.

A library folder holds custom modules, and module_utils or filter_plugins hold shared helper code Ansible auto-discovers.

Place ansible.cfg at the project root. Ansible picks up the config from your current directory, keeping settings project-local.

With this layout, one git clone gives a teammate the playbooks, inventory, variables and roles all in one consistent shape. 🎯

Here is the recommended skeleton the official docs suggest. Memorize the shape, not every file.

Which file is the conventional top-level entry point for a whole project?

You learned the standard layout: site.yml plus inventory, group_vars, host_vars and roles in one repo. A predictable shape scales with your team. ✅