You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.
This section discusses how to develop, debug, review, and test modules.
Ansible modules are reusable, standalone scripts that can be used by the Ansible API,
or by the ansible or ansible-playbook programs. They
return information to ansible by printing a JSON string to stdout before
exiting. They take arguments in one of several ways which we’ll go into
as we work through this tutorial.
See About Modules for a list of existing modules.
Modules can be written in any language and are found in the path specified
by ANSIBLE_LIBRARY or the --module-path command line option or
in the library section of the Ansible configuration file.
Before diving into the work of creating a new module, you should think about whether you actually should
develop a module. Ask the following questions:
Does a similar module already exist?
There are a lot of existing modules available. You should check out the list of existing modules at About Modules
Has someone already worked on a similar pull request?
It’s possible that someone has already started developing a similar PR. There are a few ways to find open module pull requests:
If you find an existing PR that looks like it addresses the issue you are trying to solve, please provide feedback on the PR - this will speed up getting the PR merged.
Should you use or develop an action plugin instead?
Action plugins get run on the master instead of on the target. For modules like file/copy/template, some of the work needs to be done on the master before the module executes on the target. Action plugins execute first on the master and can then execute the normal module on the target if necessary.
For more information about action plugins, read the action
plugins documentation here.
Should you use a role instead?
Check out the Roles documentation for details.
Ansible provides a number of module utilities that provide helper functions that you can use when developing your own modules. The basic.py module utility provides the main entry point for accessing the Ansible library, and all Ansible modules must, at minimum, import from basic.py:
from ansible.module_utils.basic import *
The following is a list of module_utils files and a general description. The module utility source code lives in the ./lib/module_utils directory under your main Ansible path - for more details on any specific module utility, please see the source code.
- a10.py - Utilities used by the a10_server module to manage A10 Networks devices.
- api.py - Adds shared support for generic API modules.
- aos.py - Module support utilities for managing Apstra AOS Server.
- asa.py - Module support utilities for managing Cisco ASA network devices.
- azure_rm_common.py - Definitions and utilities for Microsoft Azure Resource Manager template deployments.
- basic.py - General definitions and helper utilities for Ansible modules.
- cloudstack.py - Utilities for CloudStack modules.
- database.py - Miscellaneous helper functions for PostGRES and MySQL
- docker_common.py - Definitions and helper utilities for modules working with Docker.
- ec2.py - Definitions and utilities for modules working with Amazon EC2
- eos.py - Helper functions for modules working with EOS networking devices.
- f5.py - Helper functions for modules working with F5 networking devices.
- facts.py - Helper functions for modules that return facts.
- gce.py - Definitions and helper functions for modules that work with Google Compute Engine resources.
- ios.py - Definitions and helper functions for modules that manage Cisco IOS networking devices
- iosxr.py - Definitions and helper functions for modules that manage Cisco IOS-XR networking devices
- ismount.py - Contains single helper function that fixes os.path.ismount
- junos.py - Definitions and helper functions for modules that manage Junos networking devices
- known_hosts.py - utilities for working with known_hosts file
- mysql.py - Allows modules to connect to a MySQL instance
- netapp.py - Functions and utilities for modules that work with the NetApp storage platforms.
- netcfg.py - Configuration utility functions for use by networking modules
- netcmd.py - Defines commands and comparison operators for use in networking modules
- network.py - Functions for running commands on networking devices
- nxos.py - Contains definitions and helper functions specific to Cisco NXOS networking devices
- openstack.py - Utilities for modules that work with Openstack instances.
- openswitch.py - Definitions and helper functions for modules that manage OpenSwitch devices
- powershell.ps1 - Utilities for working with Microsoft Windows clients
- pycompat24.py - Exception workaround for Python 2.4
- rax.py - Definitions and helper functions for modules that work with Rackspace resources.
- redhat.py - Functions for modules that manage Red Hat Network registration and subscriptions
- service.py - Contains utilities to enable modules to work with Linux services (placeholder, not in use).
- shell.py - Functions to allow modules to create shells and work with shell commands
- six.py - Module utils for working with the Six Python 2 and 3 compatibility library
- splitter.py - String splitting and manipulation utilities for working with Jinja2 templates
- urls.py - Utilities for working with http and https requests
- vca.py - Contains utilities for modules that work with VMware vCloud Air
- vmware.py - Contains utilities for modules that work with VMware vSphere VMs
- vyos.py - Definitions and functions for working with VyOS networking
