mirror of https://github.com/ansible/ansible.git
[docs][backport]Backportapalooza 10 (#71621)
* Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commitpull/71648/headc586d436fa) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commitbc6461432e) * Update intro_patterns.rst (#71542) Call out the trailing comma when specifying a single host. Small snag that took me a while to notice. (cherry picked from commitec3920cef1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit215eb730e1) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commitf75223d2c6) * User guide overhaul, Table of Contents (#71553) (cherry picked from commitb694dbadfe) * update backport instructions for 2.11 (#71567) * update backport instructions in docs/docsite/rst/community/development_process.rst Co-authored-by: Matt Martz <matt@sivel.net> (cherry picked from commit7f9258b024) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit96aee766f4) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit29b20bd1b1) Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Amin Vakil <info@aminvakil.com> Co-authored-by: Matt Deacalion <matt@dirtymonkey.co.uk> Co-authored-by: Fabien Malfoy <fabien.malfoy@laposte.net> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Sandra McCann
4 years ago
committed by
GitHub
parent
7caa7e1162
commit
1af7c6c003
@ -0,0 +1,137 @@
|
||||
.. _handlers:
|
||||
|
||||
Handlers: running operations on change
|
||||
======================================
|
||||
|
||||
Sometimes you want a task to run only when a change is made on a machine. For example, you may want to restart a service if a task updates the configuration of that service, but not if the configuration is unchanged. Ansible uses handlers to address this use case. Handlers are tasks that only run when notified. Each handler should have a globally unique name.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
Handler example
|
||||
---------------
|
||||
|
||||
This playbook, ``verify-apache.yml``, contains a single play with a handler::
|
||||
|
||||
---
|
||||
- name: verify apache installation
|
||||
hosts: webservers
|
||||
vars:
|
||||
http_port: 80
|
||||
max_clients: 200
|
||||
remote_user: root
|
||||
tasks:
|
||||
- name: ensure apache is at the latest version
|
||||
yum:
|
||||
name: httpd
|
||||
state: latest
|
||||
- name: write the apache config file
|
||||
template:
|
||||
src: /srv/httpd.j2
|
||||
dest: /etc/httpd.conf
|
||||
notify:
|
||||
- restart apache
|
||||
- name: ensure apache is running
|
||||
service:
|
||||
name: httpd
|
||||
state: started
|
||||
handlers:
|
||||
- name: restart apache
|
||||
service:
|
||||
name: httpd
|
||||
state: restarted
|
||||
|
||||
In this example playbook, the second task notifies the handler. A single task can notify more than one handler::
|
||||
|
||||
- name: template configuration file
|
||||
template:
|
||||
src: template.j2
|
||||
dest: /etc/foo.conf
|
||||
notify:
|
||||
- restart memcached
|
||||
- restart apache
|
||||
handlers:
|
||||
- name: restart memcached
|
||||
service:
|
||||
name: memcached
|
||||
state: restarted
|
||||
- name: restart apache
|
||||
service:
|
||||
name: apache
|
||||
state: restarted
|
||||
|
||||
Controlling when handlers run
|
||||
-----------------------------
|
||||
|
||||
By default, handlers run after all the tasks in a particular play have been completed. This approach is efficient, because the handler only runs 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.
|
||||
|
||||
If you need handlers to run before the end of the play, add a task to flush them using the :ref:`meta module <meta_module>`, which executes Ansible actions::
|
||||
|
||||
tasks:
|
||||
- shell: some tasks go here
|
||||
- meta: flush_handlers
|
||||
- shell: some other tasks
|
||||
|
||||
The ``meta: flush_handlers`` task triggers any handlers that have been notified at that point in the play.
|
||||
|
||||
Using variables with handlers
|
||||
-----------------------------
|
||||
|
||||
You may want your Ansible handlers to use variables. For example, if the name of a service varies slightly by distribution, you want your output to show the exact name of the restarted service for each target machine. Avoid placing variables in the name of the handler. Since handler names are templated early on, Ansible may not have a value available for a handler name like this::
|
||||
|
||||
handlers:
|
||||
# this handler name may cause your play to fail!
|
||||
- name: restart "{{ web_service_name }}"
|
||||
|
||||
If the variable used in the handler name is not available, the entire play fails. Changing that variable mid-play **will not** result in newly created handler.
|
||||
|
||||
Instead, place variables in the task parameters of your handler. You can load the values using ``include_vars`` like this:
|
||||
|
||||
.. code-block:: yaml+jinja
|
||||
|
||||
tasks:
|
||||
- name: Set host variables based on distribution
|
||||
include_vars: "{{ ansible_facts.distribution }}.yml"
|
||||
|
||||
handlers:
|
||||
- name: restart web service
|
||||
service:
|
||||
name: "{{ web_service_name | default('httpd') }}"
|
||||
state: restarted
|
||||
|
||||
Handlers can also "listen" to generic topics, and tasks can notify those topics as follows::
|
||||
|
||||
handlers:
|
||||
- name: restart memcached
|
||||
service:
|
||||
name: memcached
|
||||
state: restarted
|
||||
listen: "restart web services"
|
||||
- name: restart apache
|
||||
service:
|
||||
name: apache
|
||||
state: restarted
|
||||
listen: "restart web services"
|
||||
|
||||
tasks:
|
||||
- name: restart everything
|
||||
command: echo "this task will restart the web services"
|
||||
notify: "restart web services"
|
||||
|
||||
This use makes it much easier to trigger multiple handlers. It also decouples handlers from their names,
|
||||
making it easier to share handlers among playbooks and roles (especially when using 3rd party roles from
|
||||
a shared source like Galaxy).
|
||||
|
||||
.. note::
|
||||
* Handlers always run in the order they are defined, not in the order listed in the notify-statement. This is also the case for handlers using `listen`.
|
||||
* Handler names and `listen` topics live in a global namespace.
|
||||
* Handler names are templatable and `listen` topics are not.
|
||||
* Use unique handler names. If you trigger more than one handler with the same name, the first one(s) get overwritten. Only the last one defined will run.
|
||||
* You can notify a handler defined inside a static include.
|
||||
* You cannot notify a handler defined inside a dynamic include.
|
||||
|
||||
When using handlers within roles, note that:
|
||||
|
||||
* handlers notified within ``pre_tasks``, ``tasks``, and ``post_tasks`` sections are automatically flushed in the end of section where they were notified.
|
||||
* handlers notified within ``roles`` section are automatically flushed in the end of ``tasks`` section, but before any ``tasks`` handlers.
|
||||
* handlers are play scoped and as such can be used outside of the role they are defined in.
|
||||
@ -1,27 +1,8 @@
|
||||
:orphan:
|
||||
|
||||
.. _playbooks_special_topics:
|
||||
|
||||
Advanced Playbooks Features
|
||||
Advanced playbooks features
|
||||
===========================
|
||||
|
||||
As you write more playbooks and roles, you might have some special use cases. For example, you may want to execute "dry runs" of your playbooks (:ref:`check_mode_dry`), ask playbook users to supply information (:ref:`playbooks_prompts`), retrieve information from an external datastore or API (:ref:`lookup_plugins`), or change the way Ansible handles failures (:ref:`playbooks_error_handling`). The topics listed on this page cover these use cases and many more. If you cannot achieve your goals with basic Ansible concepts and actions, browse through these topics for help with your use case.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
become
|
||||
playbooks_async
|
||||
playbooks_checkmode
|
||||
playbooks_debugger
|
||||
playbooks_delegation
|
||||
playbooks_environment
|
||||
playbooks_error_handling
|
||||
playbooks_advanced_syntax
|
||||
complex_data_manipulation
|
||||
../plugins/plugins
|
||||
playbooks_prompts
|
||||
playbooks_tags
|
||||
vault
|
||||
playbooks_startnstep
|
||||
../reference_appendices/playbooks_keywords
|
||||
playbooks_lookups
|
||||
playbooks_module_defaults
|
||||
This page is obsolete. Refer to the :ref:`main User Guide index page <user_guide_index>` for links to all playbook-related topics. Please update any links you may have made directly to this page.
|
||||
|
||||
Loading…
Reference in New Issue