You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
ansible/docs/docsite/rst/user_guide/playbooks_blocks.rst

166 lines
6.0 KiB
ReStructuredText

.. _playbooks_blocks:
******
Blocks
******
Blocks create logical groups of tasks. Blocks also offer ways to handle task errors, similar to exception handling in many programming languages.
.. contents::
:local:
Grouping tasks with blocks
==========================
All tasks in a block inherit directives applied at the block level. Most of what you can apply to a single task (with the exception of loops) can be applied at the block level, so blocks make it much easier to set data or directives common to the tasks. The directive does not affect the block itself, it is only inherited by the tasks enclosed by a block. For example, a `when` statement is applied to the tasks within a block, not to the block itself.
.. code-block:: YAML
:emphasize-lines: 3
:caption: Block example with named tasks inside the block
tasks:
- name: Install, configure, and start Apache
block:
- name: install httpd and memcached
yum:
name:
- httpd
- memcached
state: present
- name: apply the foo config template
template:
src: templates/src.j2
dest: /etc/foo.conf
- name: start service bar and enable it
service:
name: bar
state: started
enabled: True
when: ansible_facts['distribution'] == 'CentOS'
become: true
become_user: root
ignore_errors: yes
In the example above, the 'when' condition will be evaluated before Ansible runs each of the three tasks in the block. All three tasks also inherit the privilege escalation directives, running as the root user. Finally, ``ignore_errors: yes`` ensures that Ansible continues to execute the playbook even if some of the tasks fail.
Docs backportapalooza 4 (#70875) * Pipe lookup plugin usage example documentation fix (#70679) (cherry picked from commit 58d24584c0c5a60b8193df62e24477c8cc6edc7d) * Fix misleading documentation for naming blocks (#68458) From what I have observed it is the block itself that doesn't support the name attribute rather than the tasks inside the block. * Update docs/docsite/rst/user_guide/playbooks_blocks.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> (cherry picked from commit 633c2d052249703016cd3938e6bad9877fc8d189) * Fix incorrect statement to set a variable for a playbook (#70712) Fixes #70638 (cherry picked from commit 59513ae673a52675ca8f8f47e85af21b905566fd) * Make Sources, Plugins sections easier to read (#70652) Re-wrote the Inventory Sources section and also the next section to have shorter, clearer sentences with a more active voice. (cherry picked from commit fb3db170cc98279e2c7d941abdb01e2bbf96222b) * fix rstcheck problem and gitignore collections dir (#70764) (cherry picked from commit 24e5d3a51cf11586cb20b76c71350757f38f7bb3) * add note for write permission on rst files (#70766) * add note for write permission on rst files * Update docs/docsite/rst/community/documentation_contributions.rst Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> (cherry picked from commit 2a7df5e07b4d6479580803e12e4bd182509fd90e) * Modification of 'Adding modules and plugins locally' topic (#70659) * Remediated the topic to comply with IBM style guide and minimalism practices Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> (cherry picked from commit 17332532973343248297e3d3c746738d1f3b2f56) * WIP: add collections as an intersphinx link (#70826) * adds collections as a ref for intersphinx * no need for intersphinx Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com> (cherry picked from commit b28d59124b679bc3221589793440cc90cddc9b45) * Proper example for splitext filter in docs (#70494) * Update playbooks_filters.rst with a clear example of how to extract its 2 tokens. Co-authored-by: Sloane Hertel <shertel@redhat.com> (cherry picked from commit 7a42d2746200e560fa42edfe3a4e031f21411e38) * Few fixes for reference_appendices/faq.html (#70719) * Format using `` instead of `, add line breaks for long lines, rephrase or remove useless text. Move some text. * Add clearer version of OpenSSh is affected by SCP bug * Review some pages using ansible doc writing guide. (cherry picked from commit 92e16c2838182f58f2cedf25ca19273159d2246d) Co-authored-by: Roman Gorshunov <34521622+gorshunovr@users.noreply.github.com> Co-authored-by: David Rieger <david@isan.engineer> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Stef B <regendo@users.noreply.github.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Fixmetal <fixmetal@gmail.com>
4 years ago
Names for blocks have been available since Ansible 2.3. We recommend using names in all tasks, within blocks or elsewhere, for better visibility into the tasks being executed when you run the playbook.
.. _block_error_handling:
Handling errors with blocks
===========================
You can control how Ansible responds to task errors using blocks with ``rescue`` and ``always`` sections.
Rescue blocks specify tasks to run when an earlier task in a block fails. This approach is similar to exception handling in many programming languages. Ansible only runs rescue blocks after a task returns a 'failed' state. Bad task definitions and unreachable hosts will not trigger the rescue block.
.. _block_rescue:
.. code-block:: YAML
:emphasize-lines: 3,10
:caption: Block error handling example
tasks:
- name: Handle the error
block:
- debug:
msg: 'I execute normally'
- name: i force a failure
command: /bin/false
- debug:
msg: 'I never execute, due to the above task failing, :-('
rescue:
- debug:
msg: 'I caught an error, can do stuff here to fix it, :-)'
You can also add an ``always`` section to a block. Tasks in the ``always`` section run no matter what the task status of the previous block is.
.. _block_always:
.. code-block:: YAML
:emphasize-lines: 2,9
:caption: Block with always section
- name: Always do X
block:
- debug:
msg: 'I execute normally'
- name: i force a failure
command: /bin/false
- debug:
msg: 'I never execute :-('
always:
- debug:
msg: "This always executes, :-)"
Together, these elements offer complex error handling.
.. code-block:: YAML
:emphasize-lines: 2,9,16
:caption: Block with all sections
- name: Attempt and graceful roll back demo
block:
- debug:
msg: 'I execute normally'
- name: i force a failure
command: /bin/false
- debug:
msg: 'I never execute, due to the above task failing, :-('
rescue:
- debug:
msg: 'I caught an error'
- name: i force a failure in middle of recovery! >:-)
command: /bin/false
- debug:
msg: 'I also never execute :-('
always:
- debug:
msg: "This always executes"
The tasks in the ``block`` execute normally. If any tasks in the block return ``failed``, the ``rescue`` section executes tasks to recover from the error. The ``always`` section runs regardless of the results of the ``block`` and ``rescue`` sections.
If an error occurs in the block and the rescue task succeeds, Ansible reverts the failed status of the original task for the run and continues to run the play as if the original task had succeeded. The rescued task is considered successful, and does not not trigger ``max_fail_percentage`` or ``any_errors_fatal`` configurations. However, Ansible still reports a failure in the playbook statistics.
You can use blocks with ``flush_handlers`` in a rescue task to ensure that all handlers run even if an error occurs:
.. code-block:: YAML
:emphasize-lines: 6,10
:caption: Block run handlers in error handling
tasks:
- name: Attempt and graceful roll back demo
block:
- debug:
msg: 'I execute normally'
changed_when: yes
notify: run me even after an error
- command: /bin/false
rescue:
- name: make sure all handlers run
meta: flush_handlers
handlers:
- name: run me even after an error
debug:
msg: 'This handler runs even on error'
.. versionadded:: 2.1
Ansible provides a couple of variables for tasks in the ``rescue`` portion of a block:
ansible_failed_task
The task that returned 'failed' and triggered the rescue. For example, to get the name use ``ansible_failed_task.name``.
ansible_failed_result
The captured return result of the failed task that triggered the rescue. This would equate to having used this var in the ``register`` keyword.
.. seealso::
:ref:`playbooks_intro`
An introduction to playbooks
:ref:`playbooks_reuse_roles`
Playbook organization by roles
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel