Ansible/Directory Layout/Details

Example Playbooks Directory

This covers the details of the default/recommended directory layout from the Ansible documentation.

Here is the example directory layout for an Ansible playbooks/ directory:

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/               # ""

We will go through this step by step.

Hosts

The hosts file will contain information about different hosts.

If you need to separate production and staging host files, you can split hosts into production and staging, and use the -i flag when running ansible to specify an inventory file.

Group Variables

Start with how you define defaults for group variables: create an all file in the group_vars folder

---
# file: group_vars/all
ntp: ntp-boston.example.com
backup: backup-boston.example.com

If we have a group called webservers, any hosts in the webservers group will load the variables in the file group_vars/webservers. Here is an example:

---
# file: group_vars/webservers
apacheMaxRequestsPerChild: 3000
apacheMaxClients: 900

If using a group to denote geographic regions, can use that to set information about how to reach other servers (nearby ones):

---
# file: group_vars/atlanta
ntp: ntp-atlanta.example.com
backup: backup-atlanta.example.com

Host Variables

It is not encouraged to use host-specific variables - use groups when possible - but sometimes you must (e.g., changing port numbers to get around site-specific restrictions).

Example host variables file:

---
# file: host_vars/db-bos-1.example.com
foo_agent_port: 86
bar_agent_port: 99