From 79dc6fa9481c9cf7ba8d781a40ff299918495100 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 17 Sep 2020 17:20:22 +0300 Subject: [PATCH] Docsite: fix user_guide/playbooks_blocks (#71769) --- .../rst/user_guide/playbooks_blocks.rst | 86 ++++++++++++------- 1 file changed, 55 insertions(+), 31 deletions(-) diff --git a/docs/docsite/rst/user_guide/playbooks_blocks.rst b/docs/docsite/rst/user_guide/playbooks_blocks.rst index 41ca7612e8b..dc5163126da 100644 --- a/docs/docsite/rst/user_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/user_guide/playbooks_blocks.rst @@ -21,18 +21,20 @@ All tasks in a block inherit directives applied at the block level. Most of what tasks: - name: Install, configure, and start Apache block: - - name: install httpd and memcached - yum: + - name: Install httpd and memcached + ansible.builtin.yum: name: - httpd - memcached state: present - - name: apply the foo config template - template: + + - name: Apply the foo config template + ansible.builtin.template: src: templates/src.j2 dest: /etc/foo.conf - - name: start service bar and enable it - service: + + - name: Start service bar and enable it + ansible.builtin.service: name: bar state: started enabled: True @@ -62,14 +64,19 @@ Rescue blocks specify tasks to run when an earlier task in a block fails. This a tasks: - name: Handle the error block: - - debug: + - name: Print a message + ansible.builtin.debug: msg: 'I execute normally' - - name: i force a failure - command: /bin/false - - debug: + + - name: Force a failure + ansible.builtin.command: /bin/false + + - name: Never print this + ansible.builtin.debug: msg: 'I never execute, due to the above task failing, :-(' rescue: - - debug: + - name: Print when errors + ansible.builtin.debug: msg: 'I caught an error, can do stuff here to fix it, :-)' You can also add an ``always`` section to a block. Tasks in the ``always`` section run no matter what the task status of the previous block is. @@ -81,14 +88,19 @@ You can also add an ``always`` section to a block. Tasks in the ``always`` secti - name: Always do X block: - - debug: + - name: Print a message + ansible.builtin.debug: msg: 'I execute normally' - - name: i force a failure - command: /bin/false - - debug: + + - name: Force a failure + ansible.builtin.command: /bin/false + + - name: Never print this + ansible.builtin.debug: msg: 'I never execute :-(' always: - - debug: + - name: Always do this + ansible.builtin.debug: msg: "This always executes, :-)" Together, these elements offer complex error handling. @@ -99,26 +111,35 @@ Together, these elements offer complex error handling. - name: Attempt and graceful roll back demo block: - - debug: + - name: Print a message + ansible.builtin.debug: msg: 'I execute normally' - - name: i force a failure - command: /bin/false - - debug: + + - name: Force a failure + ansible.builtin.command: /bin/false + + - name: Never print this + ansible.builtin.debug: msg: 'I never execute, due to the above task failing, :-(' rescue: - - debug: + - name: Print when errors + ansible.builtin.debug: msg: 'I caught an error' - - name: i force a failure in middle of recovery! >:-) - command: /bin/false - - debug: + + - name: Force a failure in middle of recovery! >:-) + ansible.builtin.command: /bin/false + + - name: Never print this + ansible.builtin.debug: msg: 'I also never execute :-(' always: - - debug: + - name: Always do this + ansible.builtin.debug: msg: "This always executes" The tasks in the ``block`` execute normally. If any tasks in the block return ``failed``, the ``rescue`` section executes tasks to recover from the error. The ``always`` section runs regardless of the results of the ``block`` and ``rescue`` sections. -If an error occurs in the block and the rescue task succeeds, Ansible reverts the failed status of the original task for the run and continues to run the play as if the original task had succeeded. The rescued task is considered successful, and does not not trigger ``max_fail_percentage`` or ``any_errors_fatal`` configurations. However, Ansible still reports a failure in the playbook statistics. +If an error occurs in the block and the rescue task succeeds, Ansible reverts the failed status of the original task for the run and continues to run the play as if the original task had succeeded. The rescued task is considered successful, and does not trigger ``max_fail_percentage`` or ``any_errors_fatal`` configurations. However, Ansible still reports a failure in the playbook statistics. You can use blocks with ``flush_handlers`` in a rescue task to ensure that all handlers run even if an error occurs: @@ -129,17 +150,20 @@ You can use blocks with ``flush_handlers`` in a rescue task to ensure that all h tasks: - name: Attempt and graceful roll back demo block: - - debug: + - name: Print a message + ansible.builtin.debug: msg: 'I execute normally' changed_when: yes notify: run me even after an error - - command: /bin/false + + - name: Force a failure + ansible.builtin.command: /bin/false rescue: - - name: make sure all handlers run + - name: Make sure all handlers run meta: flush_handlers handlers: - - name: run me even after an error - debug: + - name: Run me even after an error + ansible.builtin.debug: msg: 'This handler runs even on error'