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>
This commit is contained in:
parent
21d692cace
commit
1de1d081a5
2 changed files with 29 additions and 4 deletions
|
@ -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…
Reference in a new issue