Docsite: fix user_guide/playbooks_handlers (#71770)

This commit is contained in:
Andrew Klychkov 2020-09-17 17:19:24 +03:00 committed by GitHub
parent 2c6661d4c1
commit 1cf42897d2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -14,49 +14,54 @@ Handler example
This playbook, ``verify-apache.yml``, contains a single play with a handler:: This playbook, ``verify-apache.yml``, contains a single play with a handler::
--- ---
- name: verify apache installation - name: Verify apache installation
hosts: webservers hosts: webservers
vars: vars:
http_port: 80 http_port: 80
max_clients: 200 max_clients: 200
remote_user: root remote_user: root
tasks: tasks:
- name: ensure apache is at the latest version - name: Ensure apache is at the latest version
yum: ansible.builtin.yum:
name: httpd name: httpd
state: latest state: latest
- name: write the apache config file
template: - name: Write the apache config file
ansible.builtin.template:
src: /srv/httpd.j2 src: /srv/httpd.j2
dest: /etc/httpd.conf dest: /etc/httpd.conf
notify: notify:
- restart apache - Restart apache
- name: ensure apache is running
service: - name: Ensure apache is running
ansible.builtin.service:
name: httpd name: httpd
state: started state: started
handlers: handlers:
- name: restart apache - name: Restart apache
service: ansible.builtin.service:
name: httpd name: httpd
state: restarted state: restarted
In this example playbook, the second task notifies the handler. A single task can notify more than one handler:: In this example playbook, the second task notifies the handler. A single task can notify more than one handler::
- name: template configuration file - name: Template configuration file
template: ansible.builtin.template:
src: template.j2 src: template.j2
dest: /etc/foo.conf dest: /etc/foo.conf
notify: notify:
- restart memcached - Restart memcached
- restart apache - Restart apache
handlers: handlers:
- name: restart memcached - name: Restart memcached
service: ansible.builtin.service:
name: memcached name: memcached
state: restarted state: restarted
- name: restart apache
service: - name: Restart apache
ansible.builtin.service:
name: apache name: apache
state: restarted state: restarted
@ -68,9 +73,14 @@ By default, handlers run after all the tasks in a particular play have been comp
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:: 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: tasks:
- shell: some tasks go here - name: Some tasks go here
- meta: flush_handlers ansible.builtin.shell: ...
- shell: some other tasks
- name: Flush handlers
meta: flush_handlers
- name: Some other tasks
ansible.builtin.shell: ...
The ``meta: flush_handlers`` task triggers any handlers that have been notified at that point in the play. The ``meta: flush_handlers`` task triggers any handlers that have been notified at that point in the play.
@ -80,8 +90,8 @@ 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:: 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: handlers:
# this handler name may cause your play to fail! # This handler name may cause your play to fail!
- name: restart "{{ web_service_name }}" - 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. 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.
@ -94,28 +104,29 @@ Instead, place variables in the task parameters of your handler. You can load th
include_vars: "{{ ansible_facts.distribution }}.yml" include_vars: "{{ ansible_facts.distribution }}.yml"
handlers: handlers:
- name: restart web service - name: Restart web service
service: ansible.builtin.service:
name: "{{ web_service_name | default('httpd') }}" name: "{{ web_service_name | default('httpd') }}"
state: restarted state: restarted
Handlers can also "listen" to generic topics, and tasks can notify those topics as follows:: Handlers can also "listen" to generic topics, and tasks can notify those topics as follows::
handlers: handlers:
- name: restart memcached - name: Restart memcached
service: ansible.builtin.service:
name: memcached name: memcached
state: restarted state: restarted
listen: "restart web services" listen: "restart web services"
- name: restart apache
service: - name: Restart apache
ansible.builtin.service:
name: apache name: apache
state: restarted state: restarted
listen: "restart web services" listen: "restart web services"
tasks: tasks:
- name: restart everything - name: Restart everything
command: echo "this task will restart the web services" ansible.builtin.command: echo "this task will restart the web services"
notify: "restart web services" notify: "restart web services"
This use makes it much easier to trigger multiple handlers. It also decouples handlers from their names, This use makes it much easier to trigger multiple handlers. It also decouples handlers from their names,
@ -132,6 +143,6 @@ a shared source like Galaxy).
When using handlers within roles, note that: 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 ``pre_tasks``, ``tasks``, and ``post_tasks`` sections are automatically flushed at 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 notified within ``roles`` section are automatically flushed at 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. * handlers are play scoped and as such can be used outside of the role they are defined in.