Run an Ansible handler only once for the entire playbook

Question

I would like to run a handler only once in an entire playbook.

I attempted using an include statement in the following in the playbook file, but this resulted in the handler being run multiple times, once for each play:

- name: Configure common config
  hosts: all
  become: true
  vars:
        OE: "{{ ansible_hostname[5] }}"
  roles:
    - { role: common }
  handlers:
    - include: handlers/main.yml

- name: Configure metadata config
  hosts: metadata
  become: true
  vars:
        OE: "{{ ansible_hostname[5] }}"
  roles:
    - { role: metadata }
  handlers:
    - include: handlers/main.yml

Here is the content of handlers/main.yml:

- name: restart autofs
  service:
    name: autofs.service
    state: restarted

Here is an example of one of the tasks that notifies the handler:

- name: Configure automount - /opt/local/xxx in /etc/auto.direct
  lineinfile:
     dest: /etc/auto.direct
     regexp: "^/opt/local/xxx"
     line: "/opt/local/xxx   -acdirmin=0,acdirmax=0,rdirplus,rw,hard,intr,bg,retry=2  nfs_server:/vol/xxx"
  notify: restart autofs

How can I get the playbook to only execute the handler once for the entire playbook?

Answer 1

The answer

The literal answer to the question in the title is: no.

Playbook is a list of plays. Playbook has no namespace, no variables, no state. All the configuration, logic, and tasks are defined in plays.

Handler is a task with a different calling schedule (not sequential, but conditional, once at the end of a play, or triggered by the meta: flush_handlers task).

A handler belongs to a play, not a playbook, and there is no way to trigger it outside of the play (i.e. at the end of the playbook).

---

Solution

The solution to the problem is possible without referring to handlers.

You can use group_by module to create an ad-hoc group based on the result of the tasks at the bottom of each play.

Then you can define a separate play at the end of the playbook restarting the service on targets belonging to the above ad-hoc group.

Refer to the below stub for the idea:

- hosts: all
  roles:
    # roles declaration
  tasks:
    - # an example task modifying Nginx configuration
      register: nginx_configuration

    # ... other tasks ...

    - name: the last task in the play
      group_by:
        key: hosts_to_restart_{{ 'nginx' if nginx_configuration is changed else '' }}

# ... other plays ...

- hosts: hosts_to_restart_nginx
  gather_facts: no
  tasks:
    - service:
        name: nginx
        state: restarted

Answer 2

It's not clear to me what your handler should do. Anyway, as for official documentation, handlers

are triggered at the end of each block of tasks in a play, and will only be triggered once even if notified by multiple different tasks [...] As of Ansible 2.2, handlers can also “listen” to generic topics, and tasks can notify those topics as follows:

So handlers are notified / executed once for each block of tasks. May be you get your goal just keeping handlers after "all" target hosts, but it doesn't seem a clean use of handlers. .

Answer 3

A handler triggered in post_tasks will run after everything else. And the handler can be set to run_once: true.

Answer 4

Possible solution

Use handlers to add hosts to in-memory inventory. Then add play to run restart service only for these hosts. See this example:

If task is changed, it notify mark to restart to set fact, that host needs service restart.

Second handler add host is quite special, because add_host task only run once for whole play even in handler, see also documentation. But if notified, it will run after marking is done implied from handlers order. Handler loops over hosts on which tasks were run and check if host service needs restart, if yes, add to special hosts_to_restart group.

Because facts are persistent across plays, notify third handler clear mark for affected hosts.

A lot of lines you hide with moving handlers to separate file and include them.

inventory file

10.1.1.[1:10]
[primary]
10.1.1.1
10.1.1.5

test.yml

---

- hosts: all
  gather_facts: no
  tasks:
      - name: Random change to notify trigger
        debug: msg="test"
        changed_when: "1|random == 1"
        notify:
            - mark to restart
            - add host
            - clear mark
  handlers:
      - name: mark to restart
        set_fact: restart_service=true
      - name: add host
        add_host:
            name: "{{item}}"
            groups: "hosts_to_restart"
        when: hostvars[item].restart_service is defined and hostvars[item].restart_service
        with_items: "{{ansible_play_batch}}"
      - name: clear mark
        set_fact: restart_service=false

- hosts: primary
  gather_facts: no
  tasks:
      - name: Change to notify trigger
        debug: msg="test"
        changed_when: true
        notify:
            - mark to restart
            - add host
            - clear mark
  handlers:
      - name: mark to restart
        set_fact: restart_service=true
      - name: add host
        add_host:
            name: "{{item}}"
            groups: "hosts_to_restart"
        when: hostvars[item].restart_service is defined and hostvars[item].restart_service
        with_items: "{{ansible_play_batch}}"
      - name: clear mark
        set_fact: restart_service=false


- hosts: hosts_to_restart
  gather_facts: no
  tasks:
      - name: Restart service
        debug: msg="Service restarted"
        changed_when: true