Red Hat Enterprise Linux Automation with Ansible

After completing this section, you should be able to create a role in a playbook's project directory and run it as part of one of the plays in the playbook.

Creating roles in Ansible requires no special development tools. Creating and using a role is a three step process:

By default, Ansible looks for roles in a subdirectory called roles in the directory containing your Ansible Playbook. This allows you to store roles with the playbook and other supporting files.

If Ansible cannot find the role there, it looks at the directories specified by the Ansible configuration setting roles_path, in order. This variable contains a colon-separated list of directories to search. The default value of this variable is:

~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles

This allows you to install roles on your system that are shared by multiple projects. For example, you could have your own roles installed your home directory in the ~/.ansible/roles subdirectory, and the system can have roles installed for all users in the /usr/share/ansible/roles directory.

Each role has its own directory with a standardized directory structure. For example, the following directory structure contains the files that define the motd role.

[user@host ~]$ tree roles/
roles/
└── motd
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    └── templates
        └── motd.j2

The README.md provides a basic human-readable description of the role, documentation and examples of how to use it, and any non-Ansible requirements it might have in order to work. The meta subdirectory contains a main.yml file that specifies information about the author, license, compatibility, and dependencies for the module. The files subdirectory contains fixed-content files and the templates subdirectory contains templates that can be deployed by the role when it is used. The other subdirectories can contain main.yml files that define default variable values, handlers, tasks, role metadata, or variables, depending on the subdirectory they are in.

If a subdirectory exists but is empty, such as handlers in this example, it is ignored. If a role does not use a feature, the subdirectory can be omitted altogether. For example, the vars subdirectory has been omitted from this example.

[user@host playbook-project]$ cd roles
[user@host roles]$ ansible-galaxy init my_new_role
- my_new_role was created successfully
[user@host roles]$ ls my_new_role/
defaults  files  handlers  meta  README.md  tasks  templates  tests  vars

Once you have created the directory structure, you must write the content of the role. A good place to start is the ROLENAME/tasks/main.yml task file, the main list of tasks run by the role.

The following tasks/main.yml file manages the /etc/motd file on managed hosts. It uses the template module to deploy the template named motd.j2 to the managed host. Because the template module is configured within a role task, instead of a playbook task, the motd.j2 template is retrieved from the role's templates subdirectory.

[user@host ~]$ cat roles/motd/tasks/main.yml
---
# tasks file for motd

- name: deliver motd file
  template:
    src: motd.j2
    dest: /etc/motd
    owner: root
    group: root
    mode: 0444

The following command displays the contents of the motd.j2 template of the motd role. It references Ansible facts and a system_owner variable.

[user@host ~]$ cat roles/motd/templates/motd.j2
This is the system {{ ansible_facts['hostname'] }}.

Today's date is: {{ ansible_facts['date_time']['date'] }}.

Only use this system with permission.
You can ask {{ system_owner }} for access.

The role defines a default value for the system_owner variable. The defaults/main.yml file in the role's directory structure is where this value is set.

The following defaults/main.yml file sets the system_owner variable to user@host.example.com. This will be the email address that is written in the /etc/motd file of managed hosts that this role is applied to.

[user@host ~]$ cat roles/motd/defaults/main.yml
---
system_owner: user@host.example.com

Role dependencies allow a role to include other roles as dependencies. For example, a role that defines a documentation server may depend upon another role that installs and configures a web server. Dependencies are defined in the meta/main.yml file in the role directory hierarchy.

The following is a sample meta/main.yml file.

---
dependencies:
  - role: apache
    port: 8080
  - role: postgres
    dbname: serverlist
    admin_user: felix

By default, roles are only added as a dependency to a playbook once. If another role also lists it as a dependency it will not be run again. This behavior can be overridden by setting the allow_duplicates variable to yes in the meta/main.yml file.

To access a role, reference it in the roles: section of a play. The following playbook refers to the motd role. Because no variables are specified, the role is applied with its default variable values.

[user@host ~]$ cat use-motd-role.yml
---
- name: use motd role playbook
  hosts: remote.example.com
  remote_user: devops
  become: true
  roles:
    - motd

When the playbook is executed, tasks performed because of a role can be identified by the role name prefix. The following sample output illustrates this with the motd : prefix in the task name:

[user@host ~]$ ansible-playbook -i inventory use-motd-role.yml

PLAY [use motd role playbook] **************************************************

TASK [setup] *******************************************************************
ok: [remote.example.com]

TASK [motd: deliver motd file] ************************************************
changed: [remote.example.com]

PLAY RECAP *********************************************************************
remote.example.com         : ok=2    changed=1    unreachable=0    failed=0

The above scenario assumes that the motd role is located in the roles directory. Later in the course you will see how to use a role that is remotely located in a version control repository.

[user@host ~]$ cat use-motd-role.yml
---
- name: use motd role playbook
  hosts: remote.example.com
  remote_user: devops
  become: true
  vars:
    system_owner: someone@host.example.com
  roles:
    - role: motd

[user@host ~]$ cat use-motd-role.yml
---
- name: use motd role playbook
  hosts: remote.example.com
  remote_user: devops
  become: true
  roles:
    - role: motd
      system_owner: someone@host.example.com