Skip to content

Included handlers can be notified, but only by the included code #2316

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

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

Included handlers can be notified, but only by the included code #2316

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0406f0d
Included handlers can be notified, but only by the included code
kpinc Dec 25, 2024
2dcf09b
Merge branch 'ansible:devel' into devel
kpinc Jan 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions docs/docsite/rst/playbook_guide/playbooks_reuse.rst
View file
Original file line number Diff line number Diff line change
@@ -116,34 +116,34 @@ Each approach to re-using distributed Ansible artifacts has advantages and limit
.. table::
:class: documentation-table

========================= ======================================== ========================================
.. Include_* Import_*
========================= ======================================== ========================================
Type of reuse Dynamic Static
========================= ================================================== ========================================
.. Include_* Import_*
========================= ================================================== ========================================
Type of reuse Dynamic Static

When processed At runtime, when encountered Pre-processed during playbook parsing
When processed At runtime, when encountered Pre-processed during playbook parsing

Task or play All includes are tasks ``import_playbook`` cannot be a task
Task or play All includes are tasks ``import_playbook`` cannot be a task

Task options Apply only to include task itself Apply to all child tasks in import
Task options Apply only to include task itself Apply to all child tasks in import

Calling from loops Executed once for each loop item Cannot be used in a loop
Calling from loops Executed once for each loop item Cannot be used in a loop

Using ``--list-tags`` Tags within includes not listed All tags appear with ``--list-tags``
Using ``--list-tags`` Tags within includes not listed All tags appear with ``--list-tags``

Using ``--list-tasks`` Tasks within includes not listed All tasks appear with ``--list-tasks``
Using ``--list-tasks`` Tasks within includes not listed All tasks appear with ``--list-tasks``

Notifying handlers Cannot trigger handlers within includes Can trigger individual imported handlers
Copy link
Contributor

Choose a reason for hiding this comment

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

@kpinc The original phrasing seems correct to me. Can you provide examples of what behavior are you referring to?

Copy link
Author

Choose a reason for hiding this comment

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

Sure. In a role I have:

 role/
   tasks/
       main.yaml
       included.yaml
   handlers/
      main.yaml

main.yaml then includes included.yaml, which notifies a handler in handlers/main.yaml. And it works.

Look what I have done. I have literally "triggered a handler within an include". The included code caused a handler to execute. There is no other way to describe what happened than "triggering a handler within an include". But the text says I can't do this.

Point being, the text is vague and can be interpreted multiple ways. It means to say that you cannot trigger a handler that is declared within an included file. But that's not what it says. And, of course, you are allowed to trigger a handler from within an include. But it does not say that this is allowed.

The text needs refinement. My change takes of no more room than the original, at least as my browser renders. And I believe what I've written clarifies things.

Copy link
Contributor

Choose a reason for hiding this comment

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

I see. Do you think Cannot notify handlers defined within includes or to be consistent with the statement about imports: Cannot notify individual included handlers be better?

Notifying handlers Including code cannot trigger included handlers Can trigger individual imported handlers

Using ``--start-at-task`` Cannot start at tasks within includes Can start at imported tasks
Using ``--start-at-task`` Cannot start at tasks within includes Can start at imported tasks

Using inventory variables Can ``include_*: {{ inventory_var }}`` Cannot ``import_*: {{ inventory_var }}``
Using inventory variables Can ``include_*: {{ inventory_var }}`` Cannot ``import_*: {{ inventory_var }}``

With playbooks No ``include_playbook`` Can import full playbooks
With playbooks No ``include_playbook`` Can import full playbooks

With variables files Can include variables files Use ``vars_files:`` to import variables
With variables files Can include variables files Use ``vars_files:`` to import variables

========================= ======================================== ========================================
========================= ================================================== ========================================


.. note::