DevOps

Tagged Ansible, ansible collections, ansible module, ansible-doc, ansible-playbook, ansible-test

Testing Custom Ansible Module

by Haris Fauzi 2020/09/23 37

There are several tests when you write Ansible module:

• compile
• sanity
• integration
• units
• documentation

With the new Ansible structure where modules have been categorized as collections, there are caveats and workaround people need to be aware of. All non-core Ansible modules are now stored in Ansible Collections, and the repos are located under https://github.com/ansible-collections/. Which means when you want to write a module you need to select the collection which matches your module.

Some of the collections are maintained by the technology provider, such as Amazon AWS. Other collections are maintained by community. If you don\'t work for Amazon AWS, and you want to contribute a new module for AWS, you will need to put your module into https://github.com/ansible-collections/community.aws instead https://github.com/ansible-collections/amazon.aws. The thing is, when you write documentation for you module, you would need to extend the documentation fragment written for amazon.aws.aws or amazon.aws.ec2 modules which belongs to the other collection.

When you want to test your documentation which refers to the doc_fragment for the other module, do the following:

1. Create a top directory where you want to store the collections, e.g. ~/src/GITHUB, let\'s call it our top directory.

   mkdir -p ~/src/GITHUB

2. Create a subdir called ansible_collections under that top directory.

   mkdir -p ~/src/GITHUB/ansible_collections

3. Download the repos from Github to the ansible_collections:

   ```
   cd ~/src/GITHUB/ansible_collections
   git clone https://github.com/ansible-collections/community.aws
   git clone https://github.com/ansible-collections/amazon.aws

4. Move the downloaded repos to the subdirectories, e.g. community.aws to community/aws/, amazon.aws to amazon/aws/

   mkdir -p [community,amazon]
   mv amazon.aws amazon/aws
   mv community.aws community/aws

5. Set some environment variables to tell ansible tools to find those collections:

   ANSIBLE_COLLECTIONS_PATHS=~/src/GITHUB
   ANSIBLE_LIBRARY=./plugins/modules
   export ANSIBLE_COLLECTIONS_PATHS ANSIBLE_LIBRARY

Running integration test would require you to navigate to the collection directory, e.g. ~/src/GITHUB/ansible_collections/community.aws, then run the ansible-test command:

cd ~/src/GITHUB/ansible_collections/community.aws
ansible-test sanity --docker ubuntu1804 plugins/modules/my_custom_module.py

Running documentation test should be part of the sanity test. To see inline documentation you can run:

ansible-doc -t module my_custom_module

This requires that ANSIBLE_LIBRARY environment variable to be set appropriately. Those two environment variables are the key to your ansible tools during module deployment.