Using and Developing Module Utilities¶
Ansible provides a number of module utilities, or snippets of shared code, that
provide helper functions 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 Python Ansible modules must import something from
ansible.module_utils
. A common option is to import AnsibleModule
:
from ansible.module_utils.basic import AnsibleModule
The ansible.module_utils
namespace is not a plain Python package: it is
constructed dynamically for each task invocation, by extracting imports and
resolving those matching the namespace against a search path derived from the
active configuration.
To reduce the maintenance burden on your own local modules, you can extract
duplicated code into one or more module utilities and import them into your modules. For example, if you have your own custom modules that import a my_shared_code
library, you can place that into a ./module_utils/my_shared_code.py
file like this:
from ansible.module_utils.my_shared_code import MySharedCodeClient
When you run ansible-playbook
, Ansible will merge any files in your local module_utils
directories into the ansible.module_utils
namespace in the order defined by the Ansible search path.
Naming and finding module utilities¶
You can generally tell what a module utility does from its name and/or its location. For example, openstack.py
contains utilities for modules that work with OpenStack instances.
Generic utilities (shared code used by many different kinds of modules) live in the common
subdirectory or in the root directory. Utilities
used by a particular set of modules generally live in a sub-directory that mirrors
the directory for those modules. For example:
lib/ansible/module_utils/urls.py
contains shared code for parsing URLslib/ansible/module_utils/storage/emc/
contains shared code related to EMClib/ansible/modules/storage/emc/
contains modules related to EMC
Following this pattern with your own module utilities makes everything easy to find and use.
Standard module utilities¶
Ansible ships with an extensive library of module_utils
files.
You can find the module
utility source code in the lib/ansible/module_utils
directory under
your main Ansible path. We’ve described the most widely used utilities below. For more details on any specific module utility,
please see the source code for module_utils.
Note
LICENSING REQUIREMENTS Ansible enforces the following licensing requirements:
- Utilities (files in
lib/ansible/module_utils/
) may have one of two licenses: A file in
module_utils
used only for a specific vendor’s hardware, provider, or service may be licensed under GPLv3+. Adding a new file undermodule_utils
with GPLv3+ needs to be approved by the core team.All other
module_utils
must be licensed under BSD, so GPL-licensed third-party and Galaxy modules can use them.If there’s doubt about the appropriate license for a file in
module_utils
, the Ansible Core Team will decide during an Ansible Core Community Meeting.
- Utilities (files in
All other files shipped with Ansible, including all modules, must be licensed under the GPL license (GPLv3 or later).
api.py
- Supports generic API modulesbasic.py
- General definitions and helper utilities for Ansible modulescommon/dict_transformations.py
- Helper functions for dictionary transformationscommon/file.py
- Helper functions for working with filescommon/text/
- Helper functions for converting and formatting text.common/parameters.py
- Helper functions for dealing with module parameterscommon/sys_info.py
- Functions for getting distribution and platform informationcommon/validation.py
- Helper functions for validating module parameters against a module argument specfacts/
- Directory of utilities for modules that return facts. See PR 23012 for more informationismount.py
- Single helper function that fixes os.path.ismountjson_utils.py
- Utilities for filtering unrelated output around module JSON output, like leading and trailing linesknown_hosts.py
- utilities for working with known_hosts filenetwork/common/config.py
- Configuration utility functions for use by networking modulesnetwork/common/netconf.py
- Definitions and helper functions for modules that use Netconf transportnetwork/common/parsing.py
- Definitions and helper functions for Network modulesnetwork/common/network.py
- Functions for running commands on networking devicesnetwork/common/utils.py
- Defines commands and comparison operators and other utilises for use in networking modulespowershell/
- Directory of definitions and helper functions for Windows PowerShell modulespycompat24.py
- Exception workaround for Python 2.4service.py
- 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 commandssix/__init__.py
- Bundled copy of the Six Python library to aid in writing code compatible with both Python 2 and Python 3splitter.py
- String splitting and manipulation utilities for working with Jinja2 templatesurls.py
- Utilities for working with http and https requests