With the introduction of collections, some content can be migrated in your own collection. This is especially useful when important content from multiple sources.

Also, as your ansible repo starts growing, you might not want to mix your inventories with your playbooks in the root folder.

Note: this post was initially a documentation PR on github

Advanced directory layout

With this setup, the root of your repo is quiet simple:

inventories/
  hosts.ini
  host_vars/
  group_vars/
    all/
      path-references.yml # See ansible-absolute-path-reference
  vaults/
playbooks/
assets/
  tasks/
  files/
  templates/
roles/ # For roles installed from ansible-galaxy
collections/
doc/ # Don't forget to fill this ;)
ansible.cfg
requirements.yml

To install and use collections from ./collections, you need to update ansible.cfg with the following:

[defaults]
collections_paths = ./collections

To install and use roles from ./roles, you need to update ansible.cfg with the following:

[defaults]
roles_path = ./roles

To use a default hosts list, you can update ansible.cfg with the following configuration:

[defaults]
inventory = ./inventories/{{ default hosts list}}

.. note: You might notice that the folders library, module_utils and filter_plugins are no longer present in this layout. This is because they should now be referenced exclusively from collections.

Organizing your inventory

First, remember to split your variables from your inventory sources (see Organizing host and group variables).

As in the traditional setup, there are still two ways to organize your inventories: within a single folder or in multiple folders. Multiple folders are particularly useful if your group_vars/host_vars don’t have that much in common in different environments.

Using a single inventory folder would look like this:

inventories/
    production                # inventory file for production servers
    staging                   # inventory file for staging environment

    group_vars/
    host_vars/

Using a multiple inventory folders would look like this:

inventories/
  production/
    hosts               # inventory file for production servers
    group_vars/
    host_vars/

  staging/
    hosts               # inventory file for staging environment
    group_vars/
    host_vars/

See also