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:
Brian Coca 2018-08-28 13:40:12 -04:00 committed by GitHub
parent ab9c4ab82d
commit 86037bc840
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 58 additions and 13 deletions

View file

@ -0,0 +1,2 @@
bugfixes:
- improved block docs

View file

@ -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 :