Module format and documentation¶
If you want to contribute your module to Ansible, you must write your module in Python and follow the standard format described below. (Unless you’re writing a Windows module, in which case the Windows guidelines apply.) In addition to following this format, you should review our submission checklist, programming tips, and strategy for maintaining Python 2 and Python 3 compatibility, as well as information about testing before you open a pull request.
Every Ansible module written in Python must begin with seven standard sections in a particular order, followed by the code. The sections in order are:
Why don’t the imports go first?
Keen Python programmers may notice that contrary to PEP 8’s advice we don’t put
imports at the top of the file. This is because the
RETURN sections are not used by the module code itself; they are essentially extra docstrings for the file. The imports are placed after these special variables for the same reason as PEP 8 puts the imports after the introductory comments and docstrings. This keeps the active parts of the code together and the pieces which are purely informational apart. The decision to exclude E402 is based on readability (which is what PEP 8 is about). Documentation strings in a module are much more similar to module level docstrings, than code, and are never utilized by the module itself. Placing the imports below this documentation and closer to the code, consolidates and groups all related code in a congruent manner to improve readability, debugging and understanding.
Copy old modules with care!
Some older modules in Ansible Core have
imports at the bottom of the file,
Copyright notices with the full GPL prefix, and/or
DOCUMENTATION fields in the wrong order. These are legacy files that need updating - do not copy them into new modules. Over time we’re updating and correcting older modules. Please follow the guidelines on this page!
Every Ansible module must begin with
#!/usr/bin/python - this “shebang” allows
ansible_python_interpreter to work.
This is immediately followed by
# -*- coding: utf-8 -*- to clarify that the file is UTF-8 encoded.
After the shebang and UTF-8 coding, there should be a copyright line with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
#!/usr/bin/python # -*- coding: utf-8 -*- # Copyright: (c) 2018, Terry Jones <[email protected]> # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
Major additions to the module (for instance, rewrites) may add additional copyright lines. Any legal review will include the source control history, so an exhaustive copyright header is not necessary. When adding a second copyright line for a significant feature or rewrite, add the newer line above the older one:
#!/usr/bin/python # -*- coding: utf-8 -*- # Copyright: (c) 2017, [New Contributor(s)] # Copyright: (c) 2015, [Original Contributor(s)] # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
Since we moved to collections we have deprecated the METADATA functionality, it is no longer required for modules, but it will not break anything if present.
After the shebang, the UTF-8 coding, the copyright line, and the license section comes the
DOCUMENTATION block. Ansible’s online module documentation is generated from the
DOCUMENTATION blocks in each module’s source code. The
DOCUMENTATION block must be valid YAML. You may find it easier to start writing your
DOCUMENTATION string in an editor with YAML syntax highlighting before you include it in your Python file. You can start by copying our example documentation string into your module file and modifying it. If you run into syntax issues in your YAML, you can validate it on the YAML Lint website.
- Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience–readable both by experts and non-experts.
- Descriptions should always start with a capital letter and end with a full stop. Consistency always helps.
- Verify that arguments in doc and module spec dict are identical.
- For password / secret arguments
no_log=Trueshould be set.
- For arguments that seem to contain sensitive information but do not contain secrets, such as “password_length”, set
no_log=Falseto disable the warning message.
- If an option is only sometimes required, describe the conditions. For example, “Required when I(state=present).”
- If your module allows
check_mode, reflect this fact in the documentation.
Each documentation field is described below. Before committing your module documentation, please test it at the command line and as HTML:
- As long as your module file is available locally, you can use
ansible-doc -t module my_module_nameto view your module documentation at the command line. Any parsing errors will be obvious - you can view details by adding
-vvvto the command.
- You should also test the HTML output of your module documentation.
All fields in the
DOCUMENTATION block are lower-case. All fields are required unless specified otherwise:
If you’re writing multiple related modules, they may share common documentation, such as authentication details, file mode settings,
seealso: entries. Rather than duplicate that information in each module’s
DOCUMENTATION block, you can save it once as a doc_fragment plugin and use it in each module’s documentation. In Ansible, shared documentation fragments are contained in a
ModuleDocFragment class in lib/ansible/plugins/doc_fragments/. To include a documentation fragment, add
extends_documentation_fragment: FRAGMENT_NAME in your module’s documentation.
Modules should only use items from a doc fragment if the module will implement all of the interface documented there in a manner that behaves the same as the existing modules which import that fragment. The goal is that items imported from the doc fragment will behave identically when used in another module that imports the doc fragment.
By default, only the
DOCUMENTATION property from a doc fragment is inserted into the module documentation. It is possible to define additional properties in the doc fragment in order to import only certain parts of a doc fragment or mix and match as appropriate. If a property is defined in both the doc fragment and the module, the module value overrides the doc fragment.
Here is an example doc fragment named
class ModuleDocFragment(object): # Standard documentation DOCUMENTATION = r''' options: # options here ''' # Additional section OTHER = r''' options: # other options here '''
To insert the contents of
OTHER in a module:
Or use both :
extends_documentation_fragment: - example_fragment - example_fragment.other
New in version 2.8.
Since Ansible 2.8, you can have user-supplied doc_fragments by using a
doc_fragments directory adjacent to play or role, just like any other plugin.
For example, all AWS modules should include:
extends_documentation_fragment: - aws - ec2
Using documentation fragments in collections describes how to incorporate documentation fragments in a collection.
After the shebang, the UTF-8 coding, the copyright line, the license section, and the
DOCUMENTATION block comes the
EXAMPLES block. Here you show users how your module works with real-world examples in multi-line plain-text YAML format. The best examples are ready for the user to copy and paste into a playbook. Review and update your examples with every change to your module.
Per playbook best practices, each example should include a
EXAMPLES = r''' - name: Ensure foo is installed modulename: name: foo state: present '''
name: line should be capitalized and not include a trailing dot.
If your examples use boolean options, use yes/no values. Since the documentation generates boolean values as yes/no, having the examples use these values as well makes the module documentation more consistent.
If your module returns facts that are often needed, an example of how to use them can be helpful.
After the shebang, the UTF-8 coding, the copyright line, the license section,
EXAMPLES blocks comes the
RETURN block. This section documents the information the module returns for use by other modules.
If your module doesn’t return anything (apart from the standard returns), this section of your module should read:
RETURN = r''' # '''
Otherwise, for each value returned, provide the following fields. All fields are required unless specified otherwise.
Name of the returned field.
Here are two example
RETURN sections, one with three simple fields and one with a complex nested field:
RETURN = r''' dest: description: Destination file/path. returned: success type: str sample: /path/to/file.txt src: description: Source file used for the copy on the target machine. returned: changed type: str sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source md5sum: description: MD5 checksum of the file after running copy. returned: when supported type: str sample: 2a5aeecc61dc98c4d780b14b330e3282 ''' RETURN = r''' packages: description: Information about package requirements returned: success type: complex contains: missing: description: Packages that are missing from the system returned: success type: list sample: - libmysqlclient-dev - libxml2-dev badversion: description: Packages that are installed but at bad versions. returned: success type: list sample: - package: libxml2-dev version: 2.9.4+dfsg1-2 constraint: ">= 3.0" '''
After the shebang, the UTF-8 coding, the copyright line, the license, and the sections for
RETURN, you can finally add the python imports. All modules must use Python imports in the form:
from module_utils.basic import AnsibleModule
The use of “wildcard” imports such as
from module_utils.basic import * is no longer allowed.