diff --git a/docs/docsite/rst/user_guide/playbooks_error_handling.rst b/docs/docsite/rst/user_guide/playbooks_error_handling.rst index ecb68571c4a..c73067cc77d 100644 --- a/docs/docsite/rst/user_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/user_guide/playbooks_error_handling.rst @@ -16,36 +16,36 @@ Ignoring failed commands By default Ansible stops executing tasks on a host when a task fails on that host. You can use ``ignore_errors`` to continue on in spite of the failure:: - - name: this will not count as a failure - command: /bin/false + - name: Do not count this as a failure + ansible.builtin.command: /bin/false ignore_errors: yes -The ``ignore_errors`` directive only works when the task is able to run and returns a value of 'failed'. It will not make Ansible ignore undefined variable errors, connection failures, execution issues (for example, missing packages), or syntax errors. +The ``ignore_errors`` directive only works when the task is able to run and returns a value of 'failed'. It does not make Ansible ignore undefined variable errors, connection failures, execution issues (for example, missing packages), or syntax errors. Ignoring unreachable host errors ================================ .. versionadded:: 2.7 -You may ignore task failure due to the host instance being 'UNREACHABLE' with the ``ignore_unreachable`` keyword. Ansible ignores the task errors, but continues to execute future tasks against the unreachable host. For example, at the task level:: +You can ignore a task failure due to the host instance being 'UNREACHABLE' with the ``ignore_unreachable`` keyword. Ansible ignores the task errors, but continues to execute future tasks against the unreachable host. For example, at the task level:: - - name: this executes, fails, and the failure is ignored - command: /bin/true + - name: This executes, fails, and the failure is ignored + ansible.builtin.command: /bin/true ignore_unreachable: yes - - name: this executes, fails, and ends the play for this host - command: /bin/true + - name: This executes, fails, and ends the play for this host + ansible.builtin.command: /bin/true And at the playbook level:: - hosts: all ignore_unreachable: yes tasks: - - name: this executes, fails, and the failure is ignored - command: /bin/true + - name: This executes, fails, and the failure is ignored + ansible.builtin.command: /bin/true - - name: this executes, fails, and ends the play for this host - command: /bin/true + - name: This executes, fails, and ends the play for this host + ansible.builtin.command: /bin/true ignore_unreachable: no .. _resetting_unreachable: @@ -84,21 +84,21 @@ Ansible lets you define what "failure" means in each task using the ``failed_whe You may check for failure by searching for a word or phrase in the output of a command:: - name: Fail task when the command error output prints FAILED - command: /usr/bin/example-command -x -y -z + ansible.builtin.command: /usr/bin/example-command -x -y -z register: command_result failed_when: "'FAILED' in command_result.stderr" or based on the return code:: - name: Fail task when both files are identical - raw: diff foo/file1 bar/file2 + ansible.builtin.raw: diff foo/file1 bar/file2 register: diff_cmd failed_when: diff_cmd.rc == 0 or diff_cmd.rc >= 2 You can also combine multiple conditions for failure. This task will fail if both conditions are true:: - name: Check if a file exists in temp and fail task if it does - command: ls /tmp/this_should_not_be_here + ansible.builtin.command: ls /tmp/this_should_not_be_here register: result failed_when: - result.rc == 0 @@ -111,7 +111,7 @@ If you want the task to fail when only one condition is satisfied, change the `` If you have too many conditions to fit neatly into one line, you can split it into a multi-line yaml value with ``>``:: - name: example of many failed_when conditions with OR - shell: "./myBinary" + ansible.builtin.shell: "./myBinary" register: ret failed_when: > ("No such file or directory" in ret.stdout) or @@ -127,17 +127,19 @@ Ansible lets you define when a particular task has "changed" a remote node using tasks: - - shell: /usr/bin/billybass --mode="take me to the river" + - name: Report 'changed' when the return code is not equal to 2 + ansible.builtin.shell: /usr/bin/billybass --mode="take me to the river" register: bass_result changed_when: "bass_result.rc != 2" - # this will never report 'changed' status - - shell: wall 'beep' + - name: This will never report 'changed' status + ansible.builtin.shell: wall 'beep' changed_when: False You can also combine multiple conditions to override "changed" result:: - - command: /bin/fake_command + - name: Combine multiple conditions to override 'changed' result + ansible.builtin.command: /bin/fake_command register: result ignore_errors: True changed_when: @@ -149,11 +151,11 @@ See :ref:`controlling_what_defines_failure` for more conditional syntax examples Ensuring success for command and shell ====================================== -The :ref:`command ` and :ref:`shell ` modules care about return codes, so if you have a command whose successful exit code is not zero, you may wish to do this:: +The :ref:`command ` and :ref:`shell ` modules care about return codes, so if you have a command whose successful exit code is not zero, you can do this:: tasks: - - name: run this command and ignore the result - shell: /usr/bin/somecommand || /bin/true + - name: Run this command and ignore the result + ansible.builtin.shell: /usr/bin/somecommand || /bin/true Aborting a play on all hosts @@ -181,25 +183,26 @@ You can use this feature when all tasks must be 100% successful to continue play --- - hosts: load_balancers_dc_a - any_errors_fatal: True + any_errors_fatal: true tasks: - - name: 'shutting down datacenter [ A ]' - command: /usr/bin/disable-dc + - name: Shut down datacenter 'A' + ansible.builtin.command: /usr/bin/disable-dc - hosts: frontends_dc_a tasks: - - name: 'stopping service' - command: /usr/bin/stop-software - - name: 'updating software' - command: /usr/bin/upgrade-software + - name: Stop service + ansible.builtin.command: /usr/bin/stop-software + + - name: Update software + ansible.builtin.command: /usr/bin/upgrade-software - hosts: load_balancers_dc_a tasks: - - name: 'Starting datacenter [ A ]' - command: /usr/bin/enable-dc + - name: Start datacenter 'A' + ansible.builtin.command: /usr/bin/enable-dc In this example Ansible starts the software upgrade on the front ends only if all of the load balancers are successfully disabled.