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.

Project Structure

Ansible - Project

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

Ansible will search for roles in the following way:

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
{{ role_path }}

Repository

Management

Create

ansible-galaxy init rolename
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

Documentation / Reference


Powered by ComboStrap