Ansible - Role

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.

Articles Related

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
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

https://galaxy.ansible.com/

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

See Ansible - Molecule (Role 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