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:

• Python shebang
• Copyright and license
• ANSIBLE_METADATA block
• DOCUMENTATION block
• EXAMPLES block
• RETURN block
• Python imports

Note

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 ANSIBLE_METADATA through 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.

Warning

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 ANSIBLE_METADATA 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!

Python shebang

Every Ansible module must begin with #!/usr/bin/python - this “shebang” allows ansible_python_interpreter to work.

Copyright and license

After the shebang, 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
 
# 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
 
# 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)

ANSIBLE_METADATA block

After the shebang, the copyright, and the license, your module file should contain an ANSIBLE_METADATA section. This section provides information about the module for use by other tools. For new modules, the following block can be simply added into your module:

ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['preview'],
                    'supported_by': 'community'}

Warning

• metadataversion is the version of the ANSIBLE_METADATA schema, _not the version of the module.
• Promoting a module’s status or supported_by status should only be done by members of the Ansible Core Team.

Ansible metadata fields

DOCUMENTATION block

After the shebang, the copyright line, the license, and the ANSIBLE_METADATA 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=True should be set.
  • If an optional parameter is sometimes required, reflect this fact in the documentation, e.g. “Required when C(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_name to view your module documentation at the command line. Any parsing errors will be obvious - you can view details by adding -vvv to the command.
• You should also test the HTML output of your module documentation.

Documentation fields

All fields in the DOCUMENTATION block are lower-case. All fields are required unless specified otherwise:

seealso::
 
# Reference by module name
- module: aci_tenant
 
# Reference by module name, including description
- module: aci_tenant
  description: ACI module to create tenants on a Cisco ACI fabric.
 
# Reference by rST documentation anchor
- ref: aci_guide
  description: Detailed information on how to manage your ACI infrastructure using Ansible.
 
# Reference by Internet resource
- name: APIC Management Information Model reference
  description: Complete reference of the APIC object model.
  link: https://developer.cisco.com/docs/apic-mim-ref/

Linking within module documentation

You can link from your module documentation to other module docs, other resources on docs.ansible.com, and resources elsewhere on the internet. The correct formats for these links are:

• L() for Links with a heading. For example: See L(IOS Platform Options guide, ../network/user_guide/platform_ios.html).
• U() for URLs. For example: See U(https://www.ansible.com/products/tower) for an overview.
• I() for option names. For example: Required if I(state=present).
• C() for files and option values. For example: If not set the environment variable C(ACME_PASSWORD) will be used.
• M() for module names. For example: See also M(win_copy) or M(win_template).

Note

• To refer a collection of modules, use C(..), e.g. Refer to the C(win_*) modules.
• Because it stands out better, using seealso is preferred for general references over the use of notes or adding links to the description.

Documentation fragments

If you’re writing multiple related modules, they may share common documentation, such as authentication details or file mode settings. Rather than duplicate that information in each module’s DOCUMENTATION block, you can save it once as a fragment and use it in each module’s documentation. Shared documentation fragments are contained in a ModuleDocFragment class in lib/ansible/utils/module_docs_fragments/. To include a documentation fragment, add extends_documentation_fragment: FRAGMENT_NAME in your module’s documentation.

For example, all AWS modules should include:

.. code-block:: yaml+jinja

extends_documentation_fragment:

• aws
• ec2

You can find more examples by searching for extends_documentation_fragment under the Ansible source tree.

EXAMPLES block

After the shebang, the copyright line, the license, the ANSIBLE_METADATA 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 name: line:

EXAMPLES = '''
- name: Ensure foo is installed
  modulename:
    name: foo
    state: present
'''

If your module returns facts that are often needed, an example of how to use them can be helpful.

RETURN block

After the shebang, the copyright line, the license, the ANSIBLE_METADATA section, DOCUMENTATION and 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 = ''' # '''Otherwise, for each value returned, provide the following fields. All fields are required unless specified otherwise.

Here are two example RETURN sections, one with three simple fields and one with a complex nested field:

RETURN = '''
dest:
    description: destination file/path
    returned: success
    type: string
    sample: /path/to/file.txt
src:
    description: source file used for the copy on the target machine
    returned: changed
    type: string
    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: string
    sample: 2a5aeecc61dc98c4d780b14b330e3282
'''
 
RETURN = '''
packages:
    description: Information about package requirements
    returned: On 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"
'''

Python imports

After the shebang, the copyright line, the license, and the sections for ANSIBLE_METADATA, DOCUMENTATION, EXAMPLES, and 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.