Ansible/Directory Layout

Option 1: one size fits all

Here is a suggested directory layout from the Ansible documentation.

group_vars directory: contains yaml files that define variables for each of the groups we define.

host_vars directory: contains yaml files that define variables for each of the hosts.

library, module_utils, and filter_utils directories: (not currently using any custom filters or modules... but this is where you would put them)

site.yml is the master playbook that defines all the plays.

There is also a sub-playbook for each role - for example, web servers or database servers.

Each role can either use the default, or define its own set of each of the following:

• tasks
• handlers
• templates
• files
• variables
• default values

(Roles expect this info to be contained in a main.yml file.)

The "common" folder defines the default values of all of the above, for all roles.

The "webserver" folder would define the above for all hosts playing a webserver role.

The "fooapp" folder would define the above for all hosts hosting the fooapp.

etc...

hosts                     # inventory file

group_vars/
   group1.yml             # here we assign variables to particular groups
   group2.yml
host_vars/
   hostname1.yml          # here we assign variables to particular systems
   hostname2.yml

library/                  # if any custom modules, put them here (optional)
module_utils/             # if any custom module_utils to support modules, put them here (optional)
filter_plugins/           # if any custom filter plugins, put them here (optional)

site.yml                  # master playbook
webservers.yml            # playbook for webservers role
dbservers.yml             # playbook for dbservers role
fooapp.yml                # playbook for foo app

roles/
    common/               # this hierarchy represents defaults for a "role"
        tasks/            #
            main.yml      #  <-- tasks file can include smaller files if warranted
        handlers/         #
            main.yml      #  <-- handlers file
        templates/        #  <-- files for use with the template resource
            ntp.conf.j2   #  <------- templates end in .j2
        files/            #
            bar.txt       #  <-- files for use with the copy resource
            foo.sh        #  <-- script files for use with the script resource
        vars/             #
            main.yml      #  <-- variables associated with this role
        defaults/         #
            main.yml      #  <-- default lower priority variables for this role
        meta/             #
            main.yml      #  <-- role dependencies
        library/          # roles can also include custom modules
        module_utils/     # roles can also include custom module_utils
        lookup_plugins/   # or other types of plugins, like lookup in this case

    webservers/           # same kind of structure as "common" was above, done for the webservers role
    dbservers/            # ""
    fooapp/               # ""

For details about each of these files (e.g., how to include what with what, how to name things in groups to work correctly, etc), see Ansible/Directory Layout/Details

Option 2: separate environments

An alternative layout that keeps the inventory file with the corresponding group and host variable files.

This is useful when the variable files for each environment are not alike, so it is easier not to try and share things.

inventories/
   production/
      hosts               # inventory file for production servers
      group_vars/
         group1.yml       # here we assign variables to particular groups
         group2.yml
      host_vars/
         hostname1.yml    # here we assign variables to particular systems
         hostname2.yml

   staging/
      hosts               # inventory file for staging environment
      group_vars/
         group1.yml       # here we assign variables to particular groups
         group2.yml
      host_vars/
         stagehost1.yml   # here we assign variables to particular systems
         stagehost2.yml

library/
module_utils/
filter_plugins/

site.yml
webservers.yml
dbservers.yml

roles/
    common/
    webtier/
    monitoring/
    fooapp/

Option 3: Ansible Galaxy

While the main role of ansible galaxy is to download roles shared by the Ansible user community, it can also be used to create a directory structure that can be populated for roles.

Use the ansible-galaxy init command to initialize a directory structure:

$ ansible-galaxy init -p <path-to-roles-directory> <name-of-role>

For example:

$ ansible-galaxy init -p playbooks/roles web

If the -p flag is not specified, the role files are created in the current directory.

Running this command creates the following files and directories:

playbooks
└── roles
    └── web
        ├── README.md
        ├── defaults
        │   └── main.yml
        ├── files
        ├── handlers
        │   └── main.yml
        ├── meta
        │   └── main.yml
        ├── tasks
        │   └── main.yml
        ├── templates
        ├── tests
        │   ├── inventory
        │   └── test.yml
        └── vars
            └── main.yml