Ansible/Directory Layout/Details

Main article: Ansible/Directory Layout

Example Playbooks Directory

This covers the details of the default/recommended directory layout from the Ansible documentation. Link: https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html#directory-layout

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.

Creating the directory structure

To make the directory structure above, you can also run:

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

For example,

ansible-galaxy init --init-path=playbooks/roles x

This will fill in the appropriate directory structure in the directory playbooks/roles/x/*

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

The webservers group can be linked to the web role.

This is done in the webservers playbook:

webservers.yml:

---
- hosts: webservers
  roles:
    - common
    - web

Note that this assumes your inventory file has assets grouped like so:

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

The database servers in the dbservers group can be connected to the db role:

dbservers.yml:

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

Roles

Main article: Ansible/Roles

Each role must define a directory structure containing files to define things like tasks, handlers, templates, etc.

This directory structure can be made by hand if there are just a few folders/things to override from the default (common) role, but here is the full directory structure:

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

Use the ansible-galaxy command to create this directory structure automatically:

ansible-galaxy init -p playbooks/roles x

This will fill in the appropriate directory structure in the directory playbooks/roles/x/*

Run for each new role as needed.

Common Role

The common role is a role that defines default values for all roles. Each subsequent role can override these settings selectively.

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

The details of each subdirectory of each role is covered on the Ansible/Roles page:

• tasks - https://charlesreid1.com/wiki/Ansible/Roles#Tasks
• files - https://charlesreid1.com/wiki/Ansible/Roles#Files
• variables - https://charlesreid1.com/wiki/Ansible/Roles#Variables_2
• defaults - https://charlesreid1.com/wiki/Ansible/Roles#Defaults_2
• handlers - https://charlesreid1.com/wiki/Ansible/Roles#Handlers