Mentions 'meta: flush_handlers' task

[JaroslavKlech]

SUMMARY

Encourage users to use meta: flush_handlers task in the test role itself

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

docs.ansible.com

Fixes #59109

[ansibot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at #docs:ansible.im and on libera IRC at #ansible-docs if you ever want to join us and chat about the docs! We meet there on Tuesdays (see the Ansible calendar) and welcome additions to our weekly agenda items - scroll down to find the upcoming agenda and add a comment to put something new on that agenda.

click here for bot help

[JaroslavKlech]

Hi @oraNod, @samccann,

feel free to review my updates.

[mkrizek]

This seems to be out of context. We do document the flush_handlers meta task in the appropriate sections.

[samccann]

We do mention them here if that helps - https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_handlers.html#controlling-when-handlers-run

[samccann]

okay rereading this and the issue that spawned this PR. Seems I put the wrong info in the issue. I think this new line likely belongs at https://github.com/ansible/ansible/blame/devel/docs/docsite/rst/reference_appendices/test_strategies.rst#L194 instead. What do you think @mkrizek ?

[JaroslavKlech]

I think @samccann meant this https://docs.ansible.com/ansible/latest/collections/ansible/builtin/meta_module.html

@mkrizek, do you think we should remove the paragraph you highlighted and instead put there a reference to https://docs.ansible.com/ansible/latest/collections/ansible/builtin/meta_module.html as it mentions "flush_handlers makes Ansible run any handler tasks which have..." ?

Thanks

[mkrizek]

I wonder if it would be better to just fix the example playbook rather than mention what could go wrong with it?
We could rewrite the playbook and move a "call" to apply_testing_checks role into post_tasks via include_role (since flush_handlers is implicitly called before post_tasks is executed). Or run flush_handlers explicitly to make the intent more obvious.

What do you think?

[JaroslavKlech]

cc: @mkrizek
I wonder if it would be better to just fix the example playbook rather... you mean to update the play/playbook that immediately precedes?

  ---
    - hosts: webservers
      serial: 5
      pre_tasks:
        - name: take out of load balancer pool
          ansible.builtin.command: /usr/bin/take_out_of_pool {{ inventory_hostname }}
          delegate_to: 127.0.0.1
      roles:
         - common
         - webserver
         - apply_testing_checks
      post_tasks:
        - name: add back to load balancer pool
          ansible.builtin.command: /usr/bin/add_back_to_pool {{ inventory_hostname }}
          delegate_to: 127.0.0.1

It sounds good that we update this playbook to make it explicit how flush_handlers should work.

[samccann]

+1 for updating the example

[JaroslavKlech]

I removed the sentence "If you need a handler to run before...", updated the post_tasks section. As to the flushing of handlers, I wonder if I should add also a task like this somewhere:

- name: Flush handlers
  meta:
    flush_handlers: yes

cc: @mkrizek

[mkrizek]

So the two options I see are:

In this example the flush_handlers is run implicitly before post_tasks.

- hosts: webservers
  serial: 5
  pre_tasks:
    - name: take out of load balancer pool
      ansible.builtin.command: /usr/bin/take_out_of_pool {{ inventory_hostname }}
      delegate_to: 127.0.0.1
  roles:
      - common
      - webserver
  post_tasks:
    - name: test the configuration
      ansible.builtin.include_role:
        name: apply_testing_checks

    - name: add back to load balancer pool
      ansible.builtin.command: /usr/bin/add_back_to_pool {{ inventory_hostname }}
      delegate_to: 127.0.0.1

or run all roles via include_role and call flush_handlers explicitly.

- hosts: webservers
  serial: 5
  pre_tasks:
    - name: take out of load balancer pool
      ansible.builtin.command: /usr/bin/take_out_of_pool {{ inventory_hostname }}
      delegate_to: 127.0.0.1
  tasks:
    - ansible.builtin.include_role:
        name: "{{ item }}"
      loop:
        - common
        - webserver
    
    - name: run any notified handlers
      ansible.builtin.meta: flush_handlers
    
    - name: test the configuration
      ansible.builtin.include_role:
        name: apply_testing_checks
  post_tasks:
    - name: add back to load balancer pool
      ansible.builtin.command: /usr/bin/add_back_to_pool {{ inventory_hostname }}
      delegate_to: 127.0.0.1

I think the second example that runs flush_handlers explicitly documents the scenario better.

[JaroslavKlech]

I went with the 2nd option -- run all roles via include_role and call flush_handlers explicitly.

[JaroslavKlech]

Hi @samccann,

if @mkrizek does not have any objections i think we can finish this pull request as I implemented his feedback.

[samccann]

Thanks @JaroslavKlech for the Ansible docs fix!