Ansible/Directory Layout/Details
From charlesreid1
Contents
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
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
Flags
