Ansible custom modules

Working within the parameters of ansible can feel very limiting, you may want to write your own modules for more flexibility. Modules can be written in any language, their ownly requirement is that your script's output is entirely json.

http://docs.ansible.com/ansible/developing_modules.html		Beginner Intro, Skeleton Module
http://docs.ansible.com/ansible/developing_plugins.html

Testing Modules

The following instructions DO work from Freebsd, where python2 is still the default python. On Archlinux however, this is not the case, and even after - modifying shebangs - creating the alias python=python2

Ansible still has trouble testing the script. Vagrant to the rescue, you can still use your full development environment from arch, and write a simple script for yourself to clone the test repo, setup the environment, along with an alias to the testmodule.

(you are, after all going to be using a VM for testing anyways, right?)

git clone git://github.com/ansible/ansible.git --recursive		## Ansible Scripts to test your modules.

## setup your current shell environment so that you
## can test modules
source ansible/hacking/env-setup
chmod +x ansible/hacking/test-module

## you'll also need to replace the She-bang with python2 in test-module.

ansible/hacking/test-module -m ./timetest.py						## This would be followed by your arguments
																				#  ex:   state=present name=something ...

Skeleton Module

#!/usr/bin/env python2
"""
When module is complete, put it in 'library' directory (?)
and run the command `make webdocs` to generate a 'docsite/testmod.html'
If your module is not being found, manually add location to
$ANSIBLE_LIBRARY environment var.
"""
from ansible.module_utils.basic import *

# =============
# Documentation
# =============

# YAML formatted documentation
DOCUMENTATION = '''
---
module:              my_module_name
short_description:   One sentence describing module
'''

# YAML example of usage
EXAMPLES = '''
- action: my_module_name   src=/path/to/src  dest=/path/to/dest

'''

# Documentation for all Output-Types
RETURN = '''
output_val_A:
    description:   what this describes
    returned:      success
    type:          string
    sample:        "/path/to/file.txt"
output_val_B:
    description:   source file used for the copy on the target machine
    returned:      changed
    type:          string
    sample:        "/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"
'''

# ====
# Core
# ====

module = AnsibleModule(
	argument_spec = dict(
		state     = dict(default='present', choices=['present', 'absent']),
		name      = dict(required=True),
		enabled   = dict(required=True, type='bool'),      ## type='bool' accepts, True,true,yes, ...
		something = dict(aliases=['whatever'])
    )
)
# Exit with Fail
module.fail_json(msg="Something fatal happened")

# Exit with Success
module.exit_json(changed=True, something_else=12345)


if __name__ == '__main__':
    main()