Ansible Custom Modules: Write Your Own Module in Python (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: installation
How to create custom Ansible modules in Python. Write, test, and distribute your own modules. AnsibleModule class, argument_spec, return values, error handling with examples.
Ansible Custom Modules: Write Your Own Module in Python (Complete Guide)
When built-in modules don't cover your use case, you can write custom Ansible modules in Python. Custom modules follow a simple pattern: accept parameters, perform actions, and return JSON results.
Minimal Module
Module Structure
Complete Module Template
Key Concepts
argument_spec
Return Values
Check Mode
Mutually Exclusive Parameters
Testing Your Module
Distribute via Collection
FAQ
What language are Ansible modules written in?
Most Ansible modules are written in Python, using the AnsibleModule class from ansible.module_utils.basic. Modules can also be written in any language that outputs JSON to stdout, but Python provides the richest framework.
Where do I put custom Ansible modules?
Place them in a library/ directory next to your playbook, in a role's library/ directory, or in a collection under plugins/modules/. Ansible discovers modules from these paths automatically.
How do I make a custom module support check mode?
Pass supports_check_mode=True to AnsibleModule(), then check module.check_mode before making changes. In check mode, report what would change without actually modifying anything.
Can I write Ansible modules in Bash or other languages?
Yes. Any executable that accepts JSON on stdin and outputs JSON to stdout works as an Ansible module. However, Python modules get the AnsibleModule helper class for argument parsing, check mode, and error handling.
How do I test custom Ansible modules?
Use python module.py <<< '{"ANSIBLE_MODULE_ARGS": {...}}' for quick tests, ansible-test sanity for code quality checks, and ansible-test units or molecule for integration testing.
Conclusion
Custom modules extend Ansible's capabilities for your specific automation needs. Follow the AnsibleModule pattern for argument parsing, check mode support, and proper error handling. Distribute modules via collections for team sharing.
Related Articles • Ansible Modules: Complete Reference • Ansible Collections: Create and Share • Ansible Development: Contributing to Ansible
Category: installation