Developing Ansible modules¶

A module is a reusable, standalone script that Ansible runs on your behalf, either locally or remotely. Modules interact with your local machine, an API, or a remote system to perform specific tasks like changing a database password or spinning up a cloud instance. Each module can be used by the Ansible API, or by the ansible or ansible-playbook programs. A module provides a defined interface, accepts arguments, and returns information to Ansible by printing a JSON string to stdout before exiting.

If you need functionality that is not available in any of the thousands of Ansible modules found in collections, you can easily write your own custom module. When you write a module for local use, you can choose any programming language and follow your own rules. Use this topic to learn how to create an Ansible module in Python. After you create a module, you must add it locally to the appropriate directory so that Ansible can find and execute it. For details about adding a module locally, see Adding modules and plugins locally.

Preparing an environment for developing Ansible modules
- Installing prerequisites via apt (Ubuntu)
- Creating a development environment (platform-agnostic steps)
Creating an info or a facts module
Creating a module
Verifying your module code
- Verifying your module code locally
- Verifying your module code in a playbook
Testing your newly-created module
- Performing sanity tests
- Adding unit tests
Contributing back to Ansible
Communication and development support
Credit

Preparing an environment for developing Ansible modules ¶

Installing prerequisites via apt (Ubuntu)¶

Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi):

sudo apt update
sudo apt install build-essential libssl-dev libffi-dev python-dev

Creating a development environment (platform-agnostic steps)¶

Clone the Ansible repository: $ git clone https://github.com/ansible/ansible.git
Change directory into the repository root dir: $ cd ansible
Create a virtual environment: $ python3 -m venv venv (or for Python 2 $ virtualenv venv. Note, this requires you to install the virtualenv package: $ pip install virtualenv)
Activate the virtual environment: $ . venv/bin/activate
Install development requirements: $ pip install -r requirements.txt
Run the environment setup script for each new dev shell process: $ . hacking/env-setup

Note

After the initial setup above, every time you are ready to start developing Ansible you should be able to just run the following from the root of the Ansible repo: $ . venv/bin/activate && . hacking/env-setup

Creating an info or a facts module ¶

Ansible gathers information about the target machines using facts modules, and gathers information on other objects or files using info modules. If you find yourself trying to add state: info or state: list to an existing module, that is often a sign that a new dedicated _facts or _info module is needed.

In Ansible 2.8 and onwards, we have two type of information modules, they are *_info and *_facts.

If a module is named <something>_facts, it should be because its main purpose is returning ansible_facts. Do not name modules that do not do this with _facts. Only use ansible_facts for information that is specific to the host machine, for example network interfaces and their configuration, which operating system and which programs are installed.

Modules that query/return general information (and not ansible_facts) should be named _info. General information is non-host specific information, for example information on online/cloud services (you can access different accounts for the same online service from the same host), or information on VMs and containers accessible from the machine, or information on individual files or programs.

Info and facts modules, are just like any other Ansible Module, with a few minor requirements:

They MUST be named <something>_info or <something>_facts, where <something> is singular.
Info *_info modules MUST return in the form of the result dictionary so other modules can access them.
Fact *_facts modules MUST return in the ansible_facts field of the result dictionary so other modules can access them.
They MUST support check_mode.
They MUST NOT make any changes to the system.
They MUST document the return fields and examples.

To create an info module:

Navigate to the correct directory for your new module: $ cd lib/ansible/modules/. If you are developing module using collection, $ cd plugins/modules/ inside your collection development tree.
Create your new module file: $ touch my_test_info.py.
Paste the content below into your new info module file. It includes the required Ansible format and documentation, a simple argument spec for declaring the module options, and some example code.
Modify and extend the code to do what you want your new info module to do. See the programming tips and Python 3 compatibility pages for pointers on writing clean and concise module code.

#!/usr/bin/python

# Copyright: (c) 2020, Your Name <YourName@example.org>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type

DOCUMENTATION = r'''
---
module: my_test_info

short_description: This is my test info module

version_added: "1.0.0"

description: This is my longer description explaining my test info module.

options:
    name:
        description: This is the message to send to the test module.
        required: true
        type: str

author:
    - Your Name (@yourGitHubHandle)
'''

EXAMPLES = r'''
# Pass in a message
- name: Test with a message
  my_namespace.my_collection.my_test_info:
    name: hello world
'''

RETURN = r'''
# These are examples of possible return values, and in general should use other names for return values.
original_message:
    description: The original name param that was passed in.
    type: str
    returned: always
    sample: 'hello world'
message:
    description: The output message that the test module generates.
    type: str
    returned: always
    sample: 'goodbye'
my_useful_info:
    description: The dictionary containing information about your system.
    type: dict
    returned: always
    sample: {
        'foo': 'bar',
        'answer': 42,
    }
'''

from ansible.module_utils.basic import AnsibleModule


def run_module():
    # define available arguments/parameters a user can pass to the module
    module_args = dict(
        name=dict(type='str', required=True),
    )

    # seed the result dict in the object
    # we primarily care about changed and state
    # changed is if this module effectively modified the target
    # state will include any data that you want your module to pass back
    # for consumption, for example, in a subsequent task
    result = dict(
        changed=False,
        original_message='',
        message='',
        my_useful_info={},
    )

    # the AnsibleModule object will be our abstraction working with Ansible
    # this includes instantiation, a couple of common attr would be the
    # args/params passed to the execution, as well as if the module
    # supports check mode
    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=True
    )

    # if the user is working with this module in only check mode we do not
    # want to make any changes to the environment, just return the current
    # state with no modifications
    if module.check_mode:
        module.exit_json(**result)

    # manipulate or modify the state as needed (this is going to be the
    # part where your module will do what it needs to do)
    result['original_message'] = module.params['name']
    result['message'] = 'goodbye'
    result['my_useful_info'] = {
        'foo': 'bar',
        'answer': 42,
    }
    # in the event of a successful module execution, you will want to
    # simple AnsibleModule.exit_json(), passing the key/value results
    module.exit_json(**result)


def main():
    run_module()


if __name__ == '__main__':
    main()

Use the same process to create a facts module.

#!/usr/bin/python

# Copyright: (c) 2020, Your Name <YourName@example.org>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type

DOCUMENTATION = r'''
---
module: my_test_facts

short_description: This is my test facts module

version_added: "1.0.0"

description: This is my longer description explaining my test facts module.

author:
    - Your Name (@yourGitHubHandle)
'''

EXAMPLES = r'''
- name: Return ansible_facts
  my_namespace.my_collection.my_test_facts:
'''

RETURN = r'''
# These are examples of possible return values, and in general should use other names for return values.
ansible_facts:
  description: Facts to add to ansible_facts.
  returned: always
  type: dict
  contains:
    foo:
      description: Foo facts about operating system.
      type: str
      returned: when operating system foo fact is present
      sample: 'bar'
    answer:
      description:
      - Answer facts about operating system.
      - This description can be a list as well.
      type: str
      returned: when operating system answer fact is present
      sample: '42'
'''

from ansible.module_utils.basic import AnsibleModule


def run_module():
    # define available arguments/parameters a user can pass to the module
    module_args = dict()

    # seed the result dict in the object
    # we primarily care about changed and state
    # changed is if this module effectively modified the target
    # state will include any data that you want your module to pass back
    # for consumption, for example, in a subsequent task
    result = dict(
        changed=False,
        ansible_facts=dict(),
    )

    # the AnsibleModule object will be our abstraction working with Ansible
    # this includes instantiation, a couple of common attr would be the
    # args/params passed to the execution, as well as if the module
    # supports check mode
    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=True
    )

    # if the user is working with this module in only check mode we do not
    # want to make any changes to the environment, just return the current
    # state with no modifications
    if module.check_mode:
        module.exit_json(**result)

    # manipulate or modify the state as needed (this is going to be the
    # part where your module will do what it needs to do)
    result['ansible_facts'] = {
        'foo': 'bar',
        'answer': '42',
    }
    # in the event of a successful module execution, you will want to
    # simple AnsibleModule.exit_json(), passing the key/value results
    module.exit_json(**result)


def main():
    run_module()


if __name__ == '__main__':
    main()

Creating a module ¶

To create a module:

Navigate to the correct directory for your new module: $ cd lib/ansible/modules/. If you are developing a module in a collection, $ cd plugins/modules/ inside your collection development tree.
Create your new module file: $ touch my_test.py.
Paste the content below into your new module file. It includes the required Ansible format and documentation, a simple argument spec for declaring the module options, and some example code.
Modify and extend the code to do what you want your new module to do. See the programming tips and Python 3 compatibility pages for pointers on writing clean and concise module code.

#!/usr/bin/python

# Copyright: (c) 2018, Terry Jones <terry.jones@example.org>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type

DOCUMENTATION = r'''
---
module: my_test

short_description: This is my test module

# If this is part of a collection, you need to use semantic versioning,
# i.e. the version is of the form "2.5.0" and not "2.4".
version_added: "1.0.0"

description: This is my longer description explaining my test module.

options:
    name:
        description: This is the message to send to the test module.
        required: true
        type: str
    new:
        description:
            - Control to demo if the result of this module is changed or not.
            - Parameter description can be a list as well.
        required: false
        type: bool
# Specify this value according to your collection
# in format of namespace.collection.doc_fragment_name
extends_documentation_fragment:
    - my_namespace.my_collection.my_doc_fragment_name

author:
    - Your Name (@yourGitHubHandle)
'''

EXAMPLES = r'''
# Pass in a message
- name: Test with a message
  my_namespace.my_collection.my_test:
    name: hello world

# pass in a message and have changed true
- name: Test with a message and changed output
  my_namespace.my_collection.my_test:
    name: hello world
    new: true

# fail the module
- name: Test failure of the module
  my_namespace.my_collection.my_test:
    name: fail me
'''

RETURN = r'''
# These are examples of possible return values, and in general should use other names for return values.
original_message:
    description: The original name param that was passed in.
    type: str
    returned: always
    sample: 'hello world'
message:
    description: The output message that the test module generates.
    type: str
    returned: always
    sample: 'goodbye'
'''

from ansible.module_utils.basic import AnsibleModule


def run_module():
    # define available arguments/parameters a user can pass to the module
    module_args = dict(
        name=dict(type='str', required=True),
        new=dict(type='bool', required=False, default=False)
    )

    # seed the result dict in the object
    # we primarily care about changed and state
    # changed is if this module effectively modified the target
    # state will include any data that you want your module to pass back
    # for consumption, for example, in a subsequent task
    result = dict(
        changed=False,
        original_message='',
        message=''
    )

    # the AnsibleModule object will be our abstraction working with Ansible
    # this includes instantiation, a couple of common attr would be the
    # args/params passed to the execution, as well as if the module
    # supports check mode
    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=True
    )

    # if the user is working with this module in only check mode we do not
    # want to make any changes to the environment, just return the current
    # state with no modifications
    if module.check_mode:
        module.exit_json(**result)

    # manipulate or modify the state as needed (this is going to be the
    # part where your module will do what it needs to do)
    result['original_message'] = module.params['name']
    result['message'] = 'goodbye'

    # use whatever logic you need to determine whether or not this module
    # made any modifications to your target
    if module.params['new']:
        result['changed'] = True

    # during the execution of the module, if there is an exception or a
    # conditional state that effectively causes a failure, run
    # AnsibleModule.fail_json() to pass in the message and the result
    if module.params['name'] == 'fail me':
        module.fail_json(msg='You requested this to fail', **result)

    # in the event of a successful module execution, you will want to
    # simple AnsibleModule.exit_json(), passing the key/value results
    module.exit_json(**result)


def main():
    run_module()


if __name__ == '__main__':
    main()

Verifying your module code ¶

After you modify the sample code above to do what you want, you can try out your module. Our debugging tips will help if you run into bugs as you verify your module code.

Verifying your module code locally ¶

If your module does not need to target a remote host, you can quickly and easily exercise your code locally like this:

Create an arguments file, a basic JSON config file that passes parameters to your module so that you can run it. Name the arguments file /tmp/args.json and add the following content:

{
    "ANSIBLE_MODULE_ARGS": {
        "name": "hello",
        "new": true
    }
}

If you are using a virtual environment (which is highly recommended for development) activate it: $ . venv/bin/activate
Set up the environment for development: $ . hacking/env-setup
Run your test module locally and directly: $ python -m ansible.modules.my_test /tmp/args.json

This should return output like this:

{"changed": true, "state": {"original_message": "hello", "new_message": "goodbye"}, "invocation": {"module_args": {"name": "hello", "new": true}}}

Verifying your module code in a playbook ¶

The next step in verifying your new module is to consume it with an Ansible playbook.

Create a playbook in any directory: $ touch testmod.yml

Add the following to the new playbook file:

- name: test my new module
  hosts: localhost
  tasks:
  - name: run the new module
    my_test:
      name: 'hello'
      new: true
    register: testout
  - name: dump test output
    debug:
      msg: '{{ testout }}'

Run the playbook and analyze the output: $ ansible-playbook ./testmod.yml

Testing your newly-created module ¶

The following two examples will get you started with testing your module code. Please review our testing section for more detailed information, including instructions for testing module documentation, adding integration tests, and more.

Note

Every new module and plugin should have integration tests, even if the tests cannot be run on Ansible CI infrastructure. In this case, the tests should be marked with the unsupported alias in aliases file.

Performing sanity tests ¶

You can run through Ansible’s sanity checks in a container:

$ ansible-test sanity -v --docker --python 2.7 MODULE_NAME

Note

Note that this example requires Docker to be installed and running. If you’d rather not use a container for this, you can choose to use --venv instead of --docker.

Adding unit tests ¶

You can add unit tests for your module in ./test/units/modules. You must first set up your testing environment. In this example, we’re using Python 3.5.

Install the requirements (outside of your virtual environment): $ pip3 install -r ./test/lib/ansible_test/_data/requirements/units.txt
Run . hacking/env-setup
To run all tests do the following: $ ansible-test units --python 3.5. If you are using a CI environment, these tests will run automatically.

Note

Ansible uses pytest for unit testing.

To run pytest against a single test module, you can run the following command. Ensure that you are providing the correct path of the test module:

$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes test/units/modules/.../test/my_test.py

Contributing back to Ansible ¶

If you would like to contribute to ansible-base by adding a new feature or fixing a bug, create a fork of the ansible/ansible repository and develop against a new feature branch using the devel branch as a starting point. When you you have a good working code change, you can submit a pull request to the Ansible repository by selecting your feature branch as a source and the Ansible devel branch as a target.

If you want to contribute a module to an Ansible collection, 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.

The Community Guide covers how to open a pull request and what happens next.

Communication and development support ¶

Join the IRC channel #ansible-devel on freenode for discussions surrounding Ansible development.

For questions and discussions pertaining to using the Ansible product, use the #ansible channel.

For more specific IRC channels look at Community Guide, Communicating.

Credit ¶

Thank you to Thomas Stringer (@trstringer) for contributing source material for this topic.