Building Custom Ansible Collections: Ship Your Own Modules Without the Pain

# io.thecodeforge — DevOps tutorial

# The old way: library/ directory in playbook repo
# playbook.yml
- hosts: all
  tasks:
    - name: Use custom module
      my_custom_module:
        param1: value

# library/my_custom_module.py lives in the same repo
# Every playbook repo has its own copy -> version drift

# io.thecodeforge — DevOps tutorial

# Example collection directory tree
my_collection/
├── galaxy.yml                # Manifest — required
├── README.md                 # Document what this does
├── requirements.yml          # Dependencies (optional)
├── plugins/
│   ├── modules/              # Your custom modules
│   │   └── my_module.py
│   ├── module_utils/         # Shared Python code
│   │   └── my_utils.py
│   ├── action/               # Action plugins
│   └── filter/               # Jinja2 filters
├── roles/                    # Reusable roles
│   └── my_role/
├── playbooks/                # Example playbooks
│   └── demo.yml
└── tests/                    # Unit and integration tests
    └── test_my_module.py

# io.thecodeforge — DevOps tutorial

#!/usr/bin/python

from ansible.module_utils.basic import AnsibleModule
import os

def run_module():
    module_args = dict(
        path=dict(type='str', required=True),
        state=dict(type='str', default='present', choices=['present', 'absent']),
    )

    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=True
    )

    path = module.params['path']
    state = module.params['state']

    result = dict(
        changed=False,
        path=path,
        exists=os.path.exists(path),
    )

    if state == 'present' and not os.path.exists(path):
        if module.check_mode:
            module.exit_json(changed=True, msg="Would create file", **result)
        # In real module, you'd create the file here
        result['changed'] = True
        result['exists'] = True
    elif state == 'absent' and os.path.exists(path):
        if module.check_mode:
            module.exit_json(changed=True, msg="Would remove file", **result)
        # Remove file logic
        result['changed'] = True
        result['exists'] = False

    module.exit_json(**result)

if __name__ == '__main__':
    run_module()

# io.thecodeforge — DevOps tutorial

# Build the collection
ansible-galaxy collection build --output-path ./dist
# Output: ./dist/my_namespace-my_collection-1.0.0.tar.gz

# Install from tarball
ansible-galaxy collection install ./dist/my_namespace-my_collection-1.0.0.tar.gz
# Installed to ~/.ansible/collections/ansible_collections/my_namespace/my_collection/

# Verify installation
ansible-galaxy collection list | grep my_namespace
# Output: my_namespace.my_collection 1.0.0

# io.thecodeforge — DevOps tutorial

from unittest import TestCase
from unittest.mock import patch, MagicMock
from ansible_collections.my_namespace.my_collection.plugins.modules.file_check import run_module

class TestFileCheckModule(TestCase):
    @patch('ansible_collections.my_namespace.my_collection.plugins.modules.file_check.AnsibleModule')
    def test_file_exists(self, mock_module):
        # Mock the module instance
        instance = mock_module.return_value
        instance.params = {'path': '/tmp/test', 'state': 'present'}
        instance.check_mode = False

        # Mock os.path.exists to return True
        with patch('os.path.exists', return_value=True):
            run_module()
            instance.exit_json.assert_called_with(
                changed=False,
                path='/tmp/test',
                exists=True
            )

    @patch('ansible_collections.my_namespace.my_collection.plugins.modules.file_check.AnsibleModule')
    def test_file_absent_check_mode(self, mock_module):
        instance = mock_module.return_value
        instance.params = {'path': '/tmp/test', 'state': 'absent'}
        instance.check_mode = True

        with patch('os.path.exists', return_value=True):
            run_module()
            instance.exit_json.assert_called_with(
                changed=True,
                msg="Would remove file",
                path='/tmp/test',
                exists=True
            )

# io.thecodeforge — DevOps tutorial

# Set API key (or use --api-key)
export ANSIBLE_GALAXY_API_KEY='your_token_here'

# Publish the collection
ansible-galaxy collection publish ./dist/my_namespace-my_collection-1.0.0.tar.gz
# Output: Successfully published collection my_namespace.my_collection version 1.0.0

# Install from Galaxy
ansible-galaxy collection install my_namespace.my_collection
# Output: Process install dependency map...
# Starting collection install process...
# Installing 'my_namespace.my_collection:1.0.0'

# io.thecodeforge — DevOps tutorial

# galaxy.yml
namespace: my_namespace
name: my_collection
version: 1.0.0
authors:
  - Your Name
description: Collection for file management
license:
  - MIT
dependencies:
  community.general: '>=5.0.0'
  ansible.posix: '>=1.0.0'
tags:
  - file
  - system
repository: https://github.com/yourorg/my_collection
documentation: https://github.com/yourorg/my_collection/docs
homepage: https://github.com/yourorg/my_collection
issues: https://github.com/yourorg/my_collection/issues

# io.thecodeforge — DevOps tutorial

# Simple alternative: use a script module
- hosts: localhost
  tasks:
    - name: Run custom script
      script: my_script.py
      args:
        executable: python3

# Or use command module with a Python one-liner
- name: Check file existence
  command: python3 -c "import os; print(os.path.exists('/tmp/test'))"
  register: result