Adding more information about blocks and blocks error handling. (ansi…

…ble#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 <[email protected]> Signed-off-by: Gabriely Pereira <[email protected]> * Apply suggestions from code review Co-Authored-By: caiohsramos <[email protected]>
pva · Apr 5, 2019 · 1de1d08 · 1de1d08
1 parent 21d692c
commit 1de1d08
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 4 deletions.
diff --git a/docs/docsite/rst/user_guide/playbooks_blocks.rst b/docs/docsite/rst/user_guide/playbooks_blocks.rst
@@ -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

diff --git a/docs/docsite/rst/user_guide/playbooks_error_handling.rst b/docs/docsite/rst/user_guide/playbooks_error_handling.rst
@@ -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::