Ansible: Create Custom Ansible Module

  • 16
Create Custom Ansible Module
Ansible + Python – Custom Module

Introduction – Ansible and Ansible Modules

Ansible is the simplest way to automate apps and IT infrastructure. Application Deployment + Configuration Management + Continuous Delivery + software provisioning. In our previous tutorials we already discussed Ansible installation and configuration, basics of Ansible i.e. How to create Ansible Playbook and how to create Ansible Roles

Ansible modules are the building blocks for building ansible playbooks. They are small pieces of python code that can be triggered from the yaml in a playbook.

Ansible provides a bunch of modules which cover most of your needs .. but sometimes not all of them! So, in this tutorial we will shown you how to create custom Ansible modules.


The Basics of Creating an Ansible Module

Here we will show you some of the must-follow basics steps to make a custom Ansible module.

  • Use common aliases across modules – name, src, dest, state
  • Modules should only be one file. If you need multiple files, you’re looking to make an action plugin not a module.
  • Modules should only return JSON; it shouldn’t be giving any errors or tracebacks.
  • All modules need to start with a shebang!

The Ansible Module Format

  • Shebang: #!/usr/bin/python
  • License agreement: the Ansible free software agreement since this is an open source product
  • Documentation: properly formatted yaml documentation (and documentation can reference other modules if needed)
  • Examples: use case for this module
  • Returns: you need to include a list of what is returned by the module
  • Functions: various functions your module needs, like changing a port on an ELB
  • Main: testing will be a nightmare if you don’t use a Main


Create a Custom Ansible Module

Most of the time there is no need to create a custom module as Ansible provides a bunch of modules which cover most of your needs. Often: We find the modules are a nice way to interact more fluently with services that provide a RESTful API. For example Github API, HashiCorp Vault API… You can, of course, interact with these services with the URI module, but it can sometimes be a little clumsy!

Let’s start with the very least and easy steps to create custom Ansible Module. Create the following file structure:




from ansible.module_utils.basic import *

def main():
        module_args = dict(
            name=dict(type='str', required=True)
	module = AnsibleModule(
	response = {"NAME": module.params['name']}
	module.exit_json(changed=False, meta=response)

if __name__ == '__main__':


  • main() is the entrypoint into your module.
  • #!/usr/bin/python is required. Shebang!
  • AnsibleModule comes from from ansible.module_utils.basic import *. It has to be imported with the *
  • AnsibleModule helps us handle incoming parameters and exiting the program (module.exit_json()). We’ll add some parameters shortly

Module Testing Using Playbooks:
To test your new module, you can create an Ansible playbook as below:

- name: Test hello module
  hosts: localhost  
    - name: run the new hello module
        name: 'Avinash Pawar'
      register: helloout

    - name: dump test output
        msg: '{{ helloout }}'

For more details and Ansible Module Development Walkthrough please visit Ansible Documentations.

As We explain above the modules are a nice way to interact more fluently with services that provide a RESTful API. So we have developed and created custom Ansible Module for Hasicorp Vault RESTful API interaction, please visit our GitHub Repo for the same.


That’s it. Congrats! You’ve successfully created a Ansible Custom Module.



Avinash Pawar

An automation enthusiast who presently working as DevOps Engineer.

More Posts - Website

Follow Me:
TwitterFacebookLinkedInGoogle Plus

Avinash Pawar

An automation enthusiast who presently working as DevOps Engineer.