Ansible module development: getting started

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

    Common environment setup

    • Clone the Ansible repository:
    • Change directory into the repository root dir: $ cd ansible
    • Create a virtual environment: $ python3 -m venv venv (or forPython 2 $ virtualenv venv. Note, this requires you to installthe 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 startdeveloping Ansible you should be able to just run the following from theroot of the Ansible repo:$ . venv/bin/activate && . hacking/env-setup

    Starting a new module

    To create a new module:

    • Navigate to the correct directory for your new module:
    • Create your new module file: $ touch my_new_test_module.py
    • Modify and extend the code to do what you want your new module to do. See the and Python 3 compatibility pages for pointers on writing clean, concise module code.

    Once you’ve modified the sample code above to do what you want, you can try out your module.Our will help if you run into bugs as you exercise your module code.

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

    • Create an arguments file, a basic JSON config file that passes parameters to your module so you can run it. Name the arguments file /tmp/args.json and add the following content:
    • If you are using a virtual environment (highly recommended fordevelopment) activate it: $ . venv/bin/activate
    • Setup the environment for development: $ . hacking/env-setup
    • Run your test module locally and directly:$ python ./my_new_test_module.py /tmp/args.json

    This should return output something like this:

    Exercising module code in a playbook

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

    • Add the following to the new playbook file:

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

    Testing basics

    These two examples will get you started with testing your module code. Please review our testing section for more detailedinformation, including instructions for , adding integration tests, and more.

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

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

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

    Unit tests

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

    • Install the requirements (outside of your virtual environment): $ pip3 install -r ./test/runner/requirements/units.txt
    • To run all tests do the following: $ ansible-test units —python 3.5 (you must run . hacking/env-setup prior to this)

    Ansible uses pytest for unit testing.

    To run pytest against a single test module, you can do the following (provide the path to the test module appropriately):

    $ pytest -r a —cov=. —cov-report=html —fulltrace —color yestest/units/modules/…/test/my_new_test_module.py

    If you would like to contribute to the main Ansible repositoryby adding a new feature or fixing a bug, of the Ansible repository and develop against a new featurebranch using the devel branch as a starting point.When you you have a good working code change, you cansubmit a pull request to the Ansible repository by selectingyour feature branch as a source and the Ansible devel branch asa target.

    If you want to contribute your module back to the upstream Ansible repo,review our submission checklist, ,and strategy for maintaining Python 2 and Python 3 compatibility, as well asinformation about 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 discussionssurrounding Ansible development.

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