/docsite/rst/playbooks_error_handling.rst

https://github.com/ajanthanm/ansible · ReStructuredText · 102 lines · 71 code · 31 blank · 0 comment · 0 complexity · 78389326d61af4a8f307db904fb9ce7a MD5 · raw file

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