Adding more information about blocks and blocks error handling. (#54429)

* Adding more information about blocks and blocks error handling.
* Update docs/docsite/rst/user_guide/playbooks_error_handling.rst and playbooks_blocks.rst
* Removing undefined variables as not rescuable errors.

Signed-off-by: Caio Ramos <caioramos97@gmail.com>
Signed-off-by: Gabriely Pereira <gabriely.pereira@usp.br>

* Apply suggestions from code review

Co-Authored-By: caiohsramos <caioramos97@gmail.com>
pull/54933/head
Caio Ramos 5 years ago committed by Alicia Cozine
parent 21d692cace
commit 1de1d081a5

@ -1,3 +1,5 @@
.. _playbooks_blocks:
Blocks
======
@ -30,20 +32,21 @@ Blocks allow for logical grouping of tasks and in play error handling. Most of w
when: ansible_facts['distribution'] == 'CentOS'
become: true
become_user: root
ignore_errors: yes
In the example above, each of the 3 tasks will be executed after appending the `when` condition from the block
and evaluating it in the task's context. Also they inherit the privilege escalation directives enabling "become to root"
for all the enclosed tasks.
for all the enclosed tasks. Finally, ``ignore_errors: yes`` will continue executing the playbook even if some of the tasks fail.
Names for tasks within 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:
Error Handling
``````````````
Blocks error handling
`````````````````````
Blocks also introduce the ability to handle errors in a way similar to exceptions in most programming languages.
Blocks only deal with 'failed' status of a task. A bad task definition, an undefined variable or an unreachable host are not `rescuable` errors.
Blocks only deal with 'failed' status of a task. A bad task definition or an unreachable host are not 'rescuable' errors.
.. _block_rescue:
.. code-block:: YAML

@ -148,6 +148,28 @@ The ``any_errors_fatal`` play option will mark all hosts as failed if any fails,
for finer-grained control ``max_fail_percentage`` can be used to abort the run after a given percentage of hosts has failed.
Using blocks
````````````
Most of what you can apply to a single task (with the exception of loops) can be applied at the :ref:`playbooks_blocks` level, which also makes it much easier to set data or directives common to the tasks.
Blocks also introduce the ability to handle errors in a way similar to exceptions in most programming languages.
Blocks only deal with 'failed' status of a task. A bad task definition or an unreachable host are not 'rescuable' errors::
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, :-)'
This will 'revert' the failed status of the outer ``block`` task for the run and the play will continue as if it had succeeded.
See :ref:`block_error_handling` for more examples.
.. seealso::

Loading…
Cancel
Save