Added a fail module in order to fail execution on certain conditions

In some cases you may want to deliberately fail the execution of a playbook. In our provisioning workflow we want to have safeguards in place to avoid provisioning systems that are already in production. Since we reboot physical and virtual systems, it is mandatory we take all the precautions to prevent accidental provisioning.

So in our use-case we have the following at the very start of the provisioning playbook:

    ### Safeguard to protect production systems
    - local_action: fail msg="System is not ready to be staged according to CMDB"
      only_if: "'$cmdb_status' != 'to-be-staged'"

and we repeat the same task in the (separate included) play that takes care of (re)booting the system using our own boot-media, so that it cannot be accidentally separately run by someone.

library/fail

@@ -0,0 +1,63 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright 2012 Dag Wieers <dag@wieers.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+DOCUMENTATION = '''
+---
+module: fail
+short_description: Fail with custom message
+description:
+     - This module fails the progress with a custom message. It can be
+       useful for bailing out when a certain condition is met using only_if.
+version_added: "0.8"
+options:
+  msg:
+    description:
+      - The customized message used for failing execution. If ommited,
+        fail will simple bail out with a generic message.
+    required: false
+    default: "Failed because only_if condition is true"
+  rc:
+    description:
+      - The return code of the failure. This is currently not used by
+        Ansible, but might be used in the future.
+    required: false
+    default: 1
+examples:
+    - code:
+        - action: fail msg="The system may not be provisioned according to the CMDB status."
+          only_if: "'$cmdb_status' != 'to-be-staged'"
+      description: "Example of how a playbook may fail when a condition is not met"
+author: Dag Wieers
+'''
+
+def main():
+
+    module = AnsibleModule(
+        argument_spec = dict(
+            msg = dict(default='Failed because only_if condition is true'),
+            rc = dict(default=1),
+        )
+    )
+
+    module.fail_json(rc=module.params['rc'], msg=module.params['msg'])
+
+# this is magic, see lib/ansible/module_common.py
+#<<INCLUDE_ANSIBLE_MODULE_COMMON>>
+main()