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

Playbooks

Now we get to the actual playbooks:

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

Master playbook: site.yml

The master playbook is the simplest, as it just includes other playbooks.

site.yml:

---
# file: site.yml
- import_playbook: webservers.yml
- import_playbook: dbservers.yml

Webservers playbook: webservers.yml

Main article: Ansible/Roles

Main article: Ansible/Separate Playbooks by Role

Now the webservers group can be linked to different roles, which can have different sets of variables, tasks, etc. defined. (Note that the name of the playbook and the name of the role do not have to be the same, this is just a simple example).

webservers.yml:

---
# file: webservers.yml
- hosts: webservers
  roles:
    - common
    - webservers

Note that this assumes your hosts/inventory file has groups, like this:

mail.example.com

[webservers]
foo.example.com
bar.example.com

[dbservers]
one.example.com
two.example.com
three.example.com

For more info on roles, see Ansible/Roles and Ansible/Separate Playbooks by Role

Database servers playbook: dbservers.yml

Main article: Ansible/Roles

Main article: Ansible/Separate Playbooks by Role

The database servers can be connected to the dbservers role and the dbservers hosts group:

dbservers.yml:

---
# file: dbservers.yml
- hosts: dbservers
  roles:
    - common
    - dbservers

Note that this assumes your hosts/inventory file has groups, like this:

mail.example.com

[webservers]
foo.example.com
bar.example.com

[dbservers]
one.example.com
two.example.com
three.example.com

For more info on roles, see Ansible/Roles and Ansible/Separate Playbooks by Role

Roles

Common role

We define a common role that sets defaults for all roles, and each subsequent role can override these as needed.

Each role must define a set of files:

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