Developing Advanced Automation with Red Hat Ansible Automation Platform

In recent versions of Ansible, you can include or import roles as a task instead of by using the roles section of the play. The advantage of this approach is that you can easily run a set of tasks, import or include a role, and then run more tasks. A potential disadvantage is that it might be less clear which roles your playbook uses without closely inspecting the playbook.

Use the include_role module to dynamically include a role, and use the import_role module to statically import a role.

The following playbook demonstrates how to include a role by using a task with the include_role module.

---
- name: Executing a role as a task
  hosts: remote.example.com

  tasks:
    - name: A normal task
      ansible.builtin.debug:
        msg: 'first task'

    - name: A task to include role2 here
      ansible.builtin.include_role:
        name: role2

    - name: Another normal task
      ansible.builtin.debug:
        msg: 'second task'

With import_role, the ansible-navigator run command starts by parsing and inserting the role in the play before starting the execution. Ansible detects and reports syntax errors immediately, and does not start executing the playbook if errors are detected.

With include_role, however, Ansible parses and inserts the role in the play when it reaches the include_role task, during the play execution. If Ansible detects syntax errors in the role, then execution of the playbook is aborted.

If you use the when directive with the include_role module, then Ansible does not parse the role if the condition in the when directive is false.

You might want a play that runs some tasks, and the handlers they notify, before your roles. You might also want to run tasks in the play after your normal tasks and handlers run. There are two directives you can use instead of tasks to do this:

The following playbook provides an example with pre_tasks, roles, tasks, post_tasks, and handlers sections. It is unusual for a play to contain all these sections.

---
- name: Deploying New Application Version
  hosts: webservers

  pre_tasks:
    # Stop monitoring the web server to avoid sending false alarms
    # while the service is updating.
    - name: Disabling Nagios for this host
      community.general.nagios:
        action: disable_alerts
        host: "{{ inventory_hostname }}"
        services: http
      delegate_to: nagios-srv

  roles:
    - role: deploy-content

  tasks:
    - name: Restarting memcached
      ansible.builtin.service:
        name: memcached
        status: restarted
      notify: Notifying the support team

    # Confirm that the application is fully operational
    # after the update.
    - name: Validating the new deployment
      ansible.builtin.uri:
        url: "http://{{ inventory_hostname }}/healthz"
        return_content: true
      register: result
      failed_when: "'OK' not in result.content"

  post_tasks:
    - name: Enabling Nagios for this host
      community.general.nagios:
        action: enable_alerts
        host: "{{ inventory_hostname }}"
        services: http
      delegate_to: nagios-srv

  handlers:
    # Send a message to the support team through Slack
    # every time the memcached service is restarted.
    - name: Notifying the support team
      community.general.slack:
        token: G922VJP25/D923DW937/3Ffe373sfhRE6y52Fg3rvf5GlK
        msg: 'Memcached on {{ inventory_hostname }} restarted'
      delegate_to: localhost
      become: false

Ansible runs the play sections in the following order:

The order of these sections in a play does not modify the order of execution, as given above. For example, if you write the tasks section before the roles section, then Ansible still runs the roles before the tasks in the tasks section. For readability, however, it is a good practice to organize your play in the order of execution: pre_tasks, roles, tasks, and post_tasks. You usually define the handlers at the end of the play.

Ansible runs and flushes notified handlers at several points during a run: after the pre_tasks section, after the roles and tasks sections, and after the post_tasks section. This means that a handler can run more than one time, at different times during play execution, if notified in multiple sections.

To immediately run any handlers that have been notified by a particular task in the play, add a task that uses the meta module with the flush_handlers parameter. This enables you to define specific points during task execution when all notified handlers are run.

In the following example, the play runs the Restart api server handler, if notified, after deploying a new configuration file and before using the application API. Without this call to the meta module, the play only calls the handler after running all of the tasks. If the handler has not run before the last task that uses the API, then that task might fail because the configuration file was updated, but the application has not yet reread the new configuration.

---
- name: Updating the application configuration and cache
  hosts: app_servers

  tasks:
    - name: Deploying the configuration file
      ansible.builtin.template:
        src: api-server.cfg.j2
        dest: /etc/api-server.cfg
      notify: Restart api server

    - name: Running all notified handlers
      ansible.builtin.meta: flush_handlers

    - name: Asking the API server to rebuild its internal cache
      ansible.builtin.uri:
        url: "https://{{ inventory_hostname }}/rest/api/2/cache/"
        method: POST
        force_basic_auth: true
        user: admin
        password: redhat
        body_format: json
        body:
          type: data
          delay: 0
        status_code: 201

  handlers:
    - name: Restart api server
      ansible.builtin.service:
        name: api-server
        state: restarted
        enabled: true

Remember that in a play, handlers have global scope. A play can notify handlers defined in roles. One role can notify a handler defined by another role or by the play.

Ansible always runs handlers that have been notified in the order they are listed in the handlers section of the play, and not in the order in which they were notified.

To summarize, a task can notify multiple handlers in at least two ways:

If the handlers are reused as a set by multiple tasks, then the easiest way to configure your playbook is to use the second approach with the listen directive. With this approach, you need only change the handlers to mark whether they are included in the set or not, and to ensure that they are listed in the correct order.

This approach is useful when a task needs to notify a lot of handlers. Instead of notifying each handler by name, the task only sends one notification. Ansible triggers all the handlers listening to that notification. This way, you can add or remove handlers without updating the task.

In the first approach, you must find and edit every affected task to add the handler to the list. You must also ensure that the handlers are listed in the correct order in the handlers section.

[user@host ~]$ cat no_handler_error.yml
---
- name: Testing notification with no handler
  hosts: localhost
  gather_facts: false
  become: false

  tasks:
    - name: Task that changes
      ansible.builtin.debug:
        msg: Trigerring a non existent handler
      changed_when: true
      notify: Restart service

[user@host ~]$ ansible-navigator run -m stdout no_handler_error.yml

PLAY [Testing notification with no handler] ******************************

TASK [Task that changes] *************************************************
ERROR! The requested handler 'Restart service' was not found in either the main handlers list nor in the listening handlers list
Please review the log for errors.