Ansible module boilerplate

ansible_module.py

DOCUMENTATION = '''
---
module: boilerplate
short_description: This is an example boilerplate module.
description:
    - Boilerplate ansible module
    - Use as a base for building your own modules and learning about how ansible modules work.
author: "Elias Nygren (@elnygren)"
options:
    state:
        description:
          - Desired state of the target
        default: present
        choices: ['present', 'absent']
    other_param:
        description:
          - What does this do?
notes:
    - remember that this is just a boilerplate/base
    - list required ENV variables, links to relevant documentations etc. here
    - Check out U(blog.emblica.fi)
requirements:
  - "python >= 2.6"
'''


#
# python core, ansible imports
#

import os
from ansible.module_utils.basic import *


#
# custom imports
#

DEPENDENCIES_OK = True  # use flag as we want to use module.fail_json for errors
try:
    import requests
except ImportError, e:
    DEPENDENCIES_OK = False


#
# Helpers
#

def run(module):
  """Run your logic here."""
  # stop execution of the module, exit successfully
  # changed: did this module perform mutations to the state of your infra?
  # kwargs: output any keys you want, you can catch those in a playbook with `register`
  module.exit_json(changed=True, data={'foo': 'bar'})


#
# Main
#

def main():
    """AnsibleModule + input validation"""
    module = AnsibleModule(
        argument_spec = dict(
            state = dict(choices=['present', 'absent'], default='present'),
            other_param = dict(type='str'),
        required_together = (
            ['state', 'other_param'],
        ),
        mutually_exclusive = (),
        required_one_of = (),
    )

    # validations and checks
    # note: module.fail_json stops execution of the module

    if not DEPENDENCIES_OK:
        module.fail_json(msg='`requests` library required for this module (`pip install requests`)')

    if len(module.params.get('other_param', '')) < 3:
        module.fail_json(msg='`other_param` value is too short!')

    # Run logic, manage errors

    try:
        run(module)
    except Exception as e:
        import traceback
        module.fail_json(msg=str(e) + str(traceback.format_exc()))


if __name__ == '__main__':
    main()

HOWTO: documentation
http://docs.ansible.com/ansible/dev_guide/developing_modules_documenting.html

HOWTO: simple module in python
http://docs.ansible.com/ansible/dev_guide/developing_modules_general.html

HOWTO: modules vs. roles vs. plugins
http://docs.ansible.com/ansible/dev_guide/developing_modules.html

HOWTO: pitfalls, best practices
http://docs.ansible.com/ansible/dev_guide/developing_modules_best_practices.html

EXAMPLE: real world, production grade module (by me)
https://github.com/UpCloudLtd/upcloud-ansible/blob/master/modules/upcloud.py

Reasonable bare minimum:

from ansible.module_utils.basic import *
module = AnsibleModule(
    argument_spec=dict(
        state=dict(choices=['present', 'absent'], default='present'),
    )
)
module.exit_json(changed=True, msg='it was a great success')