Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add details of interactions between notifications and loops #597

Open
wants to merge 2 commits into
base: devel
Choose a base branch
from
Open

Add details of interactions between notifications and loops #597

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4eca3ab
Add details of interactions between notifications and loops
lod Oct 12, 2023
8eb4561
Apply suggestions from code review
samccann Jan 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/docsite/rst/playbook_guide/playbooks_handlers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,35 @@ Tasks can instruct one or more handlers to execute using the ``notify`` keyword.
In the above example the handlers are executed on task change in the following order: ``Restart memcached``, ``Restart apache``. Handlers are executed in the order they are defined in the ``handlers`` section, not in the order listed in the ``notify`` statement. Notifying the same handler multiple times will result in executing the handler only once regardless of how many tasks notify it. For example, if multiple tasks update a configuration file and notify a handler to restart Apache, Ansible only bounces Apache once to avoid unnecessary restarts.


Notifying and loops
-------------------

Tasks can use loops to notify handlers, this is particularly useful when combined with variables to trigger multiple dynamic notifications.
samccann marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: yaml

tasks:
- name: Template services
ansible.builtin.template:
src: "{{ item }}.j2"
dest: /etc/systemd/system/{{ item }}.service
notify: Restart {{ item }}
samccann marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also add a comment inside the example, like this:

Suggested change
notify: Restart {{ item }}
# Note: if *any* loop iteration triggers a change, *all* handlers
# for this loop are run!
notify: Restart {{ item }}


handlers:
- name: Restart memcached
ansible.builtin.service:
name: memcached
state: restarted

- name: Restart apache
ansible.builtin.service:
name: apache
state: restarted

It is important to note that the notifications are triggered if the task as a whole is changed, for loops that is if any loop item changes.
samccann marked this conversation as resolved.
Show resolved Hide resolved
In the above example both memcached and apache will be restarted if either template file is changed, neither will be restarted if no file changes.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this behavior is pretty surprising (at least to me, and apparently also to the folks who created the issues in ansible/ansible) I would suggest moving this paragraph before the example, so that you read this before looking at the example. Right now when starting to read this new section, I might just look at the first paragraph and then at the example and then stop, getting the completely wrong impression of what is happening.



Naming handlers
---------------

Expand Down