/docsite/rst/playbooks_error_handling.rst

  1Error Handling In Playbooks
  2===========================
  3
  4.. contents:: Topics
  5
  6Ansible normally has defaults that make sure to check the return codes of commands and modules and
  7it fails fast -- forcing an error to be dealt with unless you decide otherwise.
  8
  9Sometimes a command that returns 0 isn't an error.  Sometimes a command might not always
 10need to report that it 'changed' the remote system.  This section describes how to change
 11the default behavior of Ansible for certain tasks so output and error handling behavior is
 12as desired.
 13
 14.. _ignoring_failed_commands:
 15
 16Ignoring Failed Commands
 17````````````````````````
 18
 19.. versionadded:: 0.6
 20
 21Generally playbooks will stop executing any more steps on a host that
 22has a failure.  Sometimes, though, you want to continue on.  To do so,
 23write a task that looks like this::
 24
 25    - name: this will not be counted as a failure
 26      command: /bin/false
 27      ignore_errors: yes
 28
 29Note that the above system only governs the failure of the particular task, so if you have an undefined
 30variable used, it will still raise an error that users will need to address.
 31
 32.. _controlling_what_defines_failure:
 33
 34Controlling What Defines Failure
 35````````````````````````````````
 36
 37.. versionadded:: 1.4
 38
 39Suppose the error code of a command is meaningless and to tell if there
 40is a failure what really matters is the output of the command, for instance
 41if the string "FAILED" is in the output.  
 42
 43Ansible in 1.4 and later provides a way to specify this behavior as follows::
 44
 45    - name: this command prints FAILED when it fails
 46      command: /usr/bin/example-command -x -y -z
 47      register: command_result
 48      failed_when: "'FAILED' in command_result.stderr"
 49
 50In previous version of Ansible, this can be still be accomplished as follows::
 51
 52    - name: this command prints FAILED when it fails
 53      command: /usr/bin/example-command -x -y -z
 54      register: command_result
 55      ignore_errors: True
 56
 57    - name: fail the play if the previous command did not succeed
 58      fail: msg="the command failed"
 59      when: "'FAILED' in command_result.stderr"
 60
 61.. _override_the_changed_result:
 62
 63Overriding The Changed Result
 64`````````````````````````````
 65
 66.. versionadded:: 1.3
 67
 68When a shell/command or other module runs it will typically report
 69"changed" status based on whether it thinks it affected machine state.
 70
 71Sometimes you will know, based on the return code
 72or output that it did not make any changes, and wish to override
 73the "changed" result such that it does not appear in report output or
 74does not cause handlers to fire::
 75
 76    tasks:
 77
 78      - shell: /usr/bin/billybass --mode="take me to the river"
 79        register: bass_result
 80        changed_when: "bass_result.rc != 2"
 81
 82      # this will never report 'changed' status
 83      - shell: wall 'beep'
 84        changed_when: False
 85
 86
 87.. seealso::
 88
 89   :doc:`playbooks`
 90       An introduction to playbooks
 91   :doc:`playbooks_best_practices`
 92       Best practices in playbooks
 93   :doc:`playbooks_conditionals`
 94       Conditional statements in playbooks
 95   :doc:`playbooks_variables`
 96       All about variables
 97   `User Mailing List <http://groups.google.com/group/ansible-devel>`_
 98       Have a question?  Stop by the google group!
 99   `irc.freenode.net <http://irc.freenode.net>`_
100       #ansible IRC chat channel
101
102