Sharing Ansible modules
#######################
:date: 2015-11-15
:summary: How to share Ansible modules

With Ansible you're expected to share roles with the Ansible Galaxy tool (either
through the `Ansible Galaxy hub <https://galaxy.ansible.com/>`_ or just using
straight git repositories). This works well enough (and personally I am using
:code:`ansible-galaxy init` to start each new role, even those that I'm not going to
share with the community). However, for sharing modules there is no such easy
solution, or is it?

Sharing with git submodule
--------------------------

I'd like to start by saying that git submodule is the poor man's package
manager and it's lack of popularity is (somewhat) justified. However, this is a
nice demonstration of a case where there is no package manager available and of
using git submodule instead. Also, I've only been able to use this technique for
modules written in Python, which is nice considering the lack of boiler-plate
that Ansible provides and that Python is my personal preference.

The whole story is really quite simple, create a separate git repository with
the modules in it. You can put them in sub-directories and as a far as I know,
there's no restriction on the hierarchy depth. In your playbook directory create
a :code:`library` directory (the Ansible default, so you can change this in
:code:`ansible.cfg`) and create an empty :code:`__init__.py` file inside that
directory. Add a git submodule inside that directory and you're done. Let's see an
example

.. code:: shell

    git init ansible-modules
    cd ansible-modules
    # Write great module
    git commit -a
    git push
    cd /path/to/your/ansible/playbook/repository
    mkdir library
    touch library/__init__.py
    git submodule add host:/path/to/ansible-modules library/my_modules
    git add .gitmodules
    git commit
    git push

Really, not that complicated. The only magic (undocumented) bit is creating a
:code:`__init__.py` file inside the :code:`library` directory, which is a 
shame that the Ansible documentation doesn't cover that. If you want to see a
real-life example, checkout my `ansible-playbooks
<https://www.shore.co.il/cgit/ansible-playbooks>`_ and `ansible-modules
<https://www.shore.co.il/cgit/ansible-modules>`_ git repos.