How To Add Custom Modules In Ansible

But, what if you need to achieve something with Ansible but a suitable module is not available ? No worries, you can write your own modules for local use; that’s the beauty of Ansible.

Also See all Community Supported Ansible Modules .

Before you start, just make sure you have searched the module library and confirmed nothing suitable for your special use.

So, how to add custom modules ?

You can write your own modules or copy modules from other people (if they have shared publicly). Here I am using the diff module by cytopia for demo purpose.

Learn more about developing a new Ansible Module .

You can add a local module in any of below locations as Ansible automatically loads all executable files found in those directories as modules.

• ~/.ansible/plugins/modules/
• /usr/share/ansible/plugins/modules/
• any directory in ANSIBLE_LIBRARY environment variable

You can search and confirm the same by checking Ansible version, you can see the paths in ansible python module location line.

$ ansible --version
ansible 2.5.1
  config file = /home/devops/ansible.cfg
  configured module search path = [u'/home/devops/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python2.7/dist-packages/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.17 (default, Nov  7 2019, 10:07:09) [GCC 7.4.0]

Aaah, I cannot find any modules there !

No need to worry, if you cannot see modules or no such path ( /home/devops/.ansible/plugins/modules or /usr/share/ansible/plugins/modules ) , as we told earlier those are default directories configured to search for modules.

You can find the path of existing modules using ansible-doc command as below.

$ ansible-doc -t module yum
> YUM    (/usr/lib/python2.7/dist-packages/ansible/modules/packaging/os/yum.py)

        Installs, upgrade, downgrades, removes, and lists packages and groups with the
        `yum' package manager. This module only works on Python 2. If you require
        Python 3 support see the [dnf] module.
.
.
<output removed>

Okay, let us add our module

Now, I am downloading diff module from github (just clone the repo or download only diff.py from repo) and move diff.py to my own module path – /home/devops/.ansible/plugins/modules

$ git clone https://github.com/cytopia/ansible-module-diff

$ ls -l ansible-module-diff/
total 52
-rwxrwxr-x 1 devops devops 11128 Feb  3 10:58 diff.py
-rw-rw-r-- 1 devops devops 35059 Feb  3 10:58 LICENSE
-rw-rw-r-- 1 devops devops  2391 Feb  3 10:58 README.md

$ mkdir -p /home/devops/.ansible/plugins/modules

$ cp ansible-module-diff/diff.py /home/devops/.ansible/plugins/modules/

Verify my module if its fetched by Ansible or not.

$ ansible-doc -t module diff
> DIFF    (/home/devops/.ansible/plugins/modules/diff.py)

        Diff compare a string, file or command output against a string file or command
        output. Check mode is only supported when diffing strings or files, commands
        will only be executed in actual run. More examples at
        https://github.com/cytopia/ansible-module-diff
.
.
<removed>

Success ! You can see module info and documentation.

Side Note

In some cases, you don’t want to share the custom module with everyone or wants to limit to some projects only.

• In that case you can keep the module inside a sub-directory – library – in the same project directory. You can specify a module path in your ansible.cfg file.

[defaults]
...
library = ./library
...

• Also you can restrict the module to use in some roles by keeping the module inside a sub-directory – library – within that role directory.