Customizing Ansible: Ansible Module Creation

Ansible: is an open source software for configuration management, provisioning and application-deployment, it comes under the Infrastructure as a code, means by writing a code we can create or deploy our infrastructure on any of the platform whether its Cloud like AWS, Azure or hypervisors etc.

Ansible Modules: is reusable & standalone code, its a main thing is to performs an certain task on the managed node or target node. Ansible module can be written in any language which can output JSON to standard output but most used and recommended way to create a custom module using python. Because Ansible is written in python and python have great support working with JSON data.

Steps to be involved in module creation using Python:

1. Create a library directory in your environment.
2. Create your module file in the library directory, library/custom_module.py
3. You can use ansible.module_utils library for custom module creation
4. Define the module inputs which we need to take from the users i.e. username, package_name etc.
5. Write a logic for a module what action need to be performed by the module and how it returns the output.
6. Test the module with every test cases to ensure it worked as expected by giving different sets of inputs & verify the output is correct or not.

Before we dive into the code, you can watch my video for a practical demo of creating a custom Ansible module using Python. It walks through the steps of adding/removing a user on a Linux system using custom modules:

📽 Watch the video tutorial here

Let’s have a look at an example.

In this example I have created a custom module to install the packages on Linux OS which uses yum as a package installer.

#!/usr/bin/python

from ansible.module_utils.basic import AnsibleModule

def install_package(module, package_name):
    cmd = "yum install -y " + package_name
    rc, stdout, stderr = module.run_command(cmd, check_rc=True)
    return stdout

def main():
    module = AnsibleModule(
        argument_spec=dict(
            package_name=dict(required=True, type='str'),
        )
    )

    package_name = module.params['package_name']

    if package_name is None:
       module.fail_json(msg='Please provide package name')
    result = install_package(module, package_name)

    module.exit_json(changed=True, msg=result)
if __name__ == '__main__':
    main()

• The module_utils the library is imported to provide access to the AnsibleModule class & it uses to handle module arguments, inputs, outputs, and errors
• The install_package the function takes in the module object and the name of the package to install as arguments. It uses the run_command method to execute the yum command and install the package.
• In the main function, an AnsibleModule object is created with the required input parameters. The install_package function is called with the package name, and the output is returned in the result variable.
• fail_json is used to handle module failures, when fail_json called it throws an error in JSON format & exit the module. Like in above example we are checking the package name is present or not. If user doesn’t provides the package name it will throws an error.
• Finally, the exit_json method is called to return the result of the module execution.

For example, to use the above module to install the httpd package, you would include the following task in your playbook:

- hosts: localhost
  tasks:
  - name: install httpd
    yum_install:
       package_name: httpd

Best Practices for custom ansible module creation:

1. Use the ansible.module_utils library.
2. Using a clear and concise module name means module name can clearly indicate that what module does.
3. Use a consistent and well-documented input format.
4. Make sure that your module handles error in well maintained manner and error messages should be helpful and informative.
5. Most important is to test the module thoroughly.

Creating custom ansible module rewarding and powerful way to automate your infrastructure & its a most powerful way to extend ansible functionality and automate more complex tasks and in this way we can also contribute to open source as for some of the tasks there are no such modules are present. By following best practices of module creation you can create high quality and easy to use ansible module. With the right approach you can unlock the full potential of ansible & so go ahead and give a try to create your own custom ansible modules.

Thank you for taking the time to read this blog till the end and learn more about creating custom Ansible modules. I hope that you found this information helpful and that it inspires you to explore the possibilities of Ansible automation. Don’t hesitate to reach out if you have any questions or feedback, and be sure to share your experiences and insights with the community.

Thanks again, and happy automating!

---

If you’re new to Ansible or looking to dive deeper, check out my Ansible Playlist on YouTube for step-by-step tutorials.