Creating Custom Ansible Modules

What You’ll Learn 📚

• Understand the basics of Ansible and its modules
• Learn how to create a simple custom module
• Progress to more complex examples
• Common questions and troubleshooting tips

Introduction to Ansible and Modules

Ansible is a powerful IT automation tool that helps you manage and configure your infrastructure. It uses modules to perform tasks. Think of modules as small programs that Ansible runs to do specific jobs, like installing software or managing files.

Modules are like the building blocks of Ansible playbooks. They do the heavy lifting for you!

Key Terminology

• Module: A reusable, standalone script that Ansible uses to perform tasks.
• Playbook: A file containing a series of tasks for Ansible to execute.
• Task: A single action performed by a module.

Getting Started: The Simplest Example

# hello_world.py
from ansible.module_utils.basic import AnsibleModule

def run_module():
    module_args = dict(
        name=dict(type='str', required=True)
    )

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

    result = dict(
        changed=False,
        message='Hello ' + module.params['name']
    )

    module.exit_json(**result)


def main():
    run_module()

if __name__ == '__main__':
    main()

Running the Module

ansible localhost -m hello_world -a "name=World"

{"changed": false, "message": "Hello World"}

Progressively Complex Examples

Example 2: File Management Module

Let’s create a module that manages files. This module will check if a file exists and create it if it doesn’t.

# file_manager.py
import os
from ansible.module_utils.basic import AnsibleModule

def run_module():
    module_args = dict(
        path=dict(type='str', required=True)
    )

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

    path = module.params['path']
    result = dict(
        changed=False,
        message='File exists'
    )

    if not os.path.exists(path):
        open(path, 'w').close()
        result['changed'] = True
        result['message'] = 'File created'

    module.exit_json(**result)


def main():
    run_module()

if __name__ == '__main__':
    main()

Example 3: User Management Module

Now, let’s create a module to manage users. This module will add a user if they don’t exist.

# user_manager.py
import pwd
import subprocess
from ansible.module_utils.basic import AnsibleModule

def run_module():
    module_args = dict(
        username=dict(type='str', required=True)
    )

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

    username = module.params['username']
    result = dict(
        changed=False,
        message='User exists'
    )

    try:
        pwd.getpwnam(username)
    except KeyError:
        subprocess.run(['useradd', username])
        result['changed'] = True
        result['message'] = 'User added'

    module.exit_json(**result)


def main():
    run_module()

if __name__ == '__main__':
    main()

Common Questions and Answers

1. What is a custom Ansible module?

   A custom Ansible module is a user-defined script that performs specific tasks not covered by built-in modules.

2. Why create custom modules?

   Custom modules allow you to extend Ansible’s functionality to meet unique requirements.

3. How do I test a custom module?

   You can test custom modules using the ansible command with the -m option.

4. What language are Ansible modules written in?

   Most Ansible modules are written in Python, but you can use other languages if needed.

Troubleshooting Common Issues

Ensure Python is installed on your system, as Ansible modules require it.

• Issue: Module not found.
  Solution: Ensure the module file is in the correct directory and named correctly.
• Issue: Syntax errors.
  Solution: Double-check your Python syntax and ensure all necessary imports are included.

Practice Exercises

1. Create a module that manages directories.
2. Modify the user management module to delete a user.
3. Experiment with adding more parameters to your modules.

Remember, practice makes perfect! Keep experimenting and you’ll become an Ansible pro in no time. 🚀

Further Resources

• Ansible Module Development Guide
• Ansible GitHub Repository