improved block docs (#43611)
* improved block docs - broke down examples per keyword - clarified which errors are handled - clarified forcing error in rescue
This commit is contained in:
parent
ab9c4ab82d
commit
86037bc840
2 changed files with 58 additions and 13 deletions
2
changelogs/fragments/blockdoc.yml
Normal file
2
changelogs/fragments/blockdoc.yml
Normal file
|
@ -0,0 +1,2 @@
|
|||
bugfixes:
|
||||
- improved block docs
|
|
@ -43,35 +43,78 @@ 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.
|
||||
|
||||
.. _block_rescue:
|
||||
.. code-block:: YAML
|
||||
:emphasize-lines: 3,9,15
|
||||
:emphasize-lines: 3,10
|
||||
:caption: Block error handling example
|
||||
|
||||
|
||||
tasks:
|
||||
- name: Attempt and graceful roll back demo
|
||||
- name: Handle the error
|
||||
block:
|
||||
- debug:
|
||||
msg: 'I execute normally'
|
||||
- command: /bin/false
|
||||
- name: i force a failure
|
||||
command: /bin/false
|
||||
- debug:
|
||||
msg: 'I never execute, due to the above task failing'
|
||||
msg: 'I never execute, due to the above task failing, :-('
|
||||
rescue:
|
||||
- debug:
|
||||
msg: 'I caught an error'
|
||||
- command: /bin/false
|
||||
msg: 'I caught an error, can do stuff here to fix it, :-)'
|
||||
|
||||
This will 'revert' the failed status of the task for the run and the play will continue as if it had succeeded.
|
||||
|
||||
There is also an ``always`` section, that will run no matter what the task status is.
|
||||
|
||||
.. _block_always:
|
||||
.. code-block:: YAML
|
||||
:emphasize-lines: 2,9
|
||||
:caption: Block with always section
|
||||
|
||||
- name: Always do X
|
||||
block:
|
||||
- debug:
|
||||
msg: 'I also never execute :-('
|
||||
msg: 'I execute normally'
|
||||
- name: i force a failure
|
||||
command: /bin/false
|
||||
- debug:
|
||||
msg: 'I never execute :-('
|
||||
always:
|
||||
- debug:
|
||||
msg: "This always executes"
|
||||
msg: "This always executes, :-)"
|
||||
|
||||
They can be added all together to do 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`` would execute normally, if there is any error the ``rescue`` section would get executed
|
||||
with whatever you need to do to recover from the previous error. The ``always`` section runs no matter what previous
|
||||
error did or did not occur in the ``block`` and ``rescue`` sections. It should be noted that the play continues if a
|
||||
``rescue`` section completes successfully as it 'erases' the error status (but not the reporting), this means it won't trigger ``max_fail_percentage`` nor ``any_errors_fatal`` configurations but will appear in the playbook statistics.
|
||||
|
||||
with whatever you need to do to recover from the previous error.
|
||||
The ``always`` section runs no matter what previous error did or did not occur in the ``block`` and ``rescue`` sections.
|
||||
It should be noted that the play continues if a ``rescue`` section completes successfully as it 'erases' the error status (but not the reporting),
|
||||
this means it won't trigger ``max_fail_percentage`` nor ``any_errors_fatal`` configurations but will appear in the playbook statistics.
|
||||
|
||||
Another example is how to run handlers after an error occurred :
|
||||
|
||||
|
|
Loading…
Reference in a new issue