About
Roles is the reusable unit of Ansible. You may think of it as a function.
It:
- helps make playbook content self-contained
- works well with things like git submodules for sharing content with others.
Project Structure
Roles expect files to be in certain directory names.
site.yml
webservers.yml
fooservers.yml
roles/
common/
main.yml
tasks/
handlers/
files/
templates/
vars/
defaults/
meta/
webservers/
main.yml
tasks/
defaults/
meta/
where:
- main.yml
- tasks - contains the main list of tasks to be executed by the role.
- handlers - contains handlers, which may be used by this role or even anywhere outside this role.
- defaults - default variables for the role
- defaults/main.yml
- or defaults/main/whatever.yml
- vars - other variables for the role
- files - contains files which can be deployed via this role.
- templates - contains templates which can be deployed via this role.
- meta - defines some meta data for this role.
Docker
Example: Galaxy Role
Variable
Role variable section
Search
Ansible will search for roles in the following way:
- A roles/ directory, relative to the playbook file.
- in the role path
Path
The role path is where ansible will search for a role.
By default: ~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles
The role path may be overwritten via:
- the env ANSIBLE_ROLES_PATH
- the roles_path property in an ansible.cfg file.
- the –roles-path option of the ansible-galaxy command. Example
ansible-galaxy install --roles-path . geerlingguy.apache
- you can use it in a playbook
{{ role_path }}
Repository
Management
Create
- Create a new skeleton with ansible-galaxy
ansible-galaxy init rolename
- or via a collection
ansible-galaxy collection init
- or with molecule
molecule init role -r my-new-role
Execute
Playbook
Via a Ansible - Playbook (Doc)
- Classic (original) way - treated as static imports and processed during playbook parsing.
---
- hosts: webservers
roles:
- common
- webservers
vars:
dir: '/opt/b'
app_port: 5001
- '/path/to/my/roles/common'
vars:
dir: '/opt/a'
app_port: 5000
tasks:
...
- or with tagging
---
- hosts: webservers
roles:
- {role: 'common', tags: 'common' }
- {role: 'webservers', tags: 'webservers' }
- {role: 'mysql', tags: 'mysql'}
- {role: 'apache', tags: 'apache'}
- only apache
ansible-playbook webserver.yml --tags "apache"
Ad-hoc
With ansible
ansible -m include_role -a 'name=rolname' myhosts
Example with the ansible directory as subdirectory:
ansible -i ansible/hosts-local.ini --playbook-dir=ansible -m include_role -a 'name=rolname' hostPattern
Dependency
Role dependencies are always executed before the role that includes them, and may be recursive.
Test
Install
from Ansible galaxy (installing-roles or galaxy Installing content)
ansible-galaxy install namespace.role_name,version
# or
ansible-galaxy install git+url,(commit|branch)
# or an installation in the working directory
ansible-galaxy install --roles-path . namespace.role_name
Example:
ansible-galaxy install geerlingguy.apache,v1.0.0
# git
ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25
If the role path is not specified via the roles-path option at the command line:
- the env ANSIBLE_ROLES_PATH is checked
- otherwise the ansible.cfg file is checked (where roles_path can be set)
- otherwise the installation will take place to the first writable directory
- ~/.ansible/roles
- /usr/share/ansible/roles
- /etc/ansible/roles
List
All installed roles can be listed with the following command:
ansible-galaxy list