From 1de1d081a57749df893e8e502138fa8b835f9526 Mon Sep 17 00:00:00 2001 From: Caio Ramos Date: Fri, 5 Apr 2019 18:49:20 -0300 Subject: [PATCH] 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 Signed-off-by: Gabriely Pereira * Apply suggestions from code review Co-Authored-By: caiohsramos --- .../rst/user_guide/playbooks_blocks.rst | 11 ++++++---- .../user_guide/playbooks_error_handling.rst | 22 +++++++++++++++++++ 2 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/user_guide/playbooks_blocks.rst b/docs/docsite/rst/user_guide/playbooks_blocks.rst index 5550e025255..2e8b900e8e5 100644 --- 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 index 882dceb5d11..2cdfc691c5f 100644 --- 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::