Ansible Training – 12. Ansible Module Development

Docs: 12.1 Ansible Module Development - Basics

Mon, 01 Jan 0001 00:00:00 +0000

In this lab we are going to learn how Ansible uses modules and where to find information about developing a custom module.

Task 1

In which language has a module to be written?
Point your webbrowser to the official documentation about Ansible module architecture.
Point your webbrowser to the official documentation about developing modules.
Point your webbrowser to the official documentation about developing modules best practices.
Point your webbrowser to the official documentation about developing collections.
Point your webbrowser to the official documentation about debugging your module.
Which environment variable lets you keep the remote module files after executing the module (instead of deleting it)?

Solution Task 1

All done?

Ansible module development on YouTube
Have a look at the Puzzle OPNsense Ansible Collection

Docs: 12.2 Environment Setup

Mon, 01 Jan 0001 00:00:00 +0000

In this section, we’ll dive into setting up an isolated Python environment specifically tailored for Ansible module development. We’ll be using pipenv, a powerful tool that simplifies dependency management and virtual environment creation.

Why Use Virtual Environments?

When working on multiple Python projects, it’s crucial to isolate their dependencies. Different projects might rely on different versions of the same library, or even different Python versions altogether. Installing packages globally can lead to conflicts and break existing projects. Virtual environments solve this problem by creating isolated spaces where you can install project-specific dependencies without affecting other projects or the system-wide Python installation.

Note

This section covers a Python environment setup using pipenv. If you are already well-versed with Python and any other environment management tool like poetry, venv, uv, etc., feel free to skip this section. However, keep in mind that you still need to install the necessary package ansible-dev-tools within your chosen environment.

Introducing `pipenv`

pipenv is a modern tool designed to handle both virtual environments and dependency management in Python projects. It streamlines the process of:

Creating and managing virtual environments: pipenv automatically creates a virtual environment for your project in the current directory or a specified location and handles all activation for you.
Managing dependencies: It uses a Pipfile to track your project’s dependencies and a Pipfile.lock to ensure reproducible builds.
Simplified workflow: It offers intuitive commands for installing, uninstalling, and updating packages.

Task 1

Let’s have a closer look at the ansible-dev-tools package.

The ansible-dev-tools package is a curated collection of essential tools for developing, testing, and maintaining Ansible content. It significantly simplifies the development workflow by bundling together frequently used utilities. You can find detailed information about it here: Ansible Development Tools Documentation.

What useful ansible-tools does ansible-dev-tools contain?

Solution Task 1

Here’s a breakdown of the key packages included:

ansible-builder: Automates the process of building Ansible execution environments using schemas and tooling defined in Ansible Collections.
ansible-core: The core Ansible automation engine, enabling configuration management, application deployment, and task automation.
ansible-creator: A tool designed for efficiently generating Ansible content, helping to streamline development and content creation.
ansible-dev-environment: A pip-like install for Ansible collections.
ansible-lint: Analyzes playbooks and identifies areas for improvement in terms of best practices and potential issues.
ansible-navigator: Provides a text-based user interface (TUI) for interacting with and managing Ansible.
ansible-sign: Utility for signing and verifying Ansible project directory contents.
molecule: Aids in the development and testing of various Ansible content types, including collections, playbooks, and roles.
pytest-ansible: A plugin that allows using Ansible within pytest tests, and it helps in using pytest as a collection unit test runner, while also allowing molecule scenarios as pytest fixtures.
tox-ansible: Provides a method to create a matrix of Python and Ansible environments to run tests for Ansible collections, both locally and with Github actions.

Task 2

First of all, lets make sure we have a more recent python version installed with pip on our lab controller node:

1

sudo dnf install python3.12 python3.12-pip

Now let’s proceed and install pipenv globally as a python3.12 package (While at it let’s also upgrade pip):

1

python3.12 -m pip install -U pip pipenv

Can you tell what pipenv version has been installed on your system?

Solution Task 2

You can get the pipenv version by running the following:

1

pipenv --version

The output may look like this

1
2


 $ pipenv --version
pipenv, version 2024.4.1

Task 3

Let’s create a new project with a dedicated virtual environment. The project should reside in the folder /home/ansible/techlab/ansible-module-development.

Create your project directory and navigate there:

1
2


mkdir -p /home/ansible/techlab/ansible-module-development
cd /home/ansible/techlab/ansible-module-development

Create the virtual environment: To create the virtual environment run:
1

pipenv --python 3.12
What happened with this command?

Solution Task 3

It created a Pipfile and a Pipfile.lock in the current directory.
A virtual environment has been created at pipenv --venv.

Task 4

In this techlab we rely on the version 25.5.1 of the ansible-dev-tools package. Can you find out how to install it in your new pipenv?

Solution Task 4

1

pipenv install ansible-dev-tools==25.5.1

This will add ansible-dev-tools to your Pipfile and install it within the project’s virtual environment.
The version of the package is explicitly set in the [packages] directive of the Pipfile.
pipenv also automatically updates the Pipfile.lock, so other developers can get the exact same dependency versions.

Note on Version-Specific Dependency Installation

When installing dependencies with pipenv, it’s highly recommended to specify the exact version you need, like this: pipenv install ansible-dev-tools==25.5.1, instead of just pipenv install ansible-dev-tools. This ensures version locking, reproducible builds, prevents unexpected breakage, ensures an explicit dependency and compatibility. In short, always be explicit about the version you want to install. You can always update to a newer version later (after testing it!), but starting with a locked version provides a much more stable foundation.

Task 5

To start working within your virtual environment, you need to “activate” it. pipenv makes this super easy:

1

pipenv shell

This command will launch a new shell session within the virtual environment.

How can you verify if the shell is active?

Solution Task 4

You can verify that the virtual environments python interpreter is used by checking the output of which python. If the python interpreter is located inside the virtualenv at the location of pipenv --venv your virtual environment is active.
You could also verify if any of the installed dependencies are available by e.g. running ansible or any other command from the ansible-dev-tools package.

Deactivating the Environment

To exit the virtual environment and return to your system’s default shell, simply type:

1

exit

All done?

Docs: 12.3 Creating a Local Module

Mon, 01 Jan 0001 00:00:00 +0000

Before we dive further into the bells and whistles of collections and other ansible dev tools, let’s start with a simple module. Most likely you will encounter use-cases that will not justify the overhead of maintaining a collection. In those cases it is still possible to create a local module and use it in your playbooks in a much easier and more appropriate way.

Setup

To do so, we need to configure Ansible to look for our custom modules at a specified location.

We can tell Ansible where to look for custom modules by either setting the ANSIBLE_LIBRARY environment variable or by setting the library option in the defaults section of the ansible.cfg file.

Let’s use the ansible.cfg approach for this and set the library option to a local folder ./library.

Solution Task 1

The ansible.cfg file should look like this:

1
2


[defaults]
library = ./library

Do not forget to create the library folder:

1

mkdir -p ./library

Ansible Module Structure

Let’s have a look at the example module of the official documentation. From the code of the my_test.py module we can identify the key elements required to write a module:

1. Some boilerplate code

Ansible modules must start with this boilerplate code.

1
2
3
4
5
6


#!/usr/bin/python
# Copyright: (c) 2025, Your Name <your@email.ch>
# 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

This ensures that the module can be executed as a standalone module using python 2 and 3.

2. The `DOCUMENTATION` block

This block contains information about the module and its arguments. Ansible tooling uses this information to generate documentation for the ansible-doc output and the antsibull-doc HTML pages. For this reason this block must adhere to a specific format, which is thoroughly documented in the official documentation.

3. The `EXAMPLES` block

This block contains examples of how to use the module. Just like the DOCUMENTATION block, this block must adhere to a specific format. The specification is documented in the official documentation as well.

4. The `RETURN` block

Finally, the RETURN block contains information about the return values of the module. Again, this block must adhere to a specific format. The specification is documented in the official documentation.

5. The main function

The main function contains the code of the module. There are only a few rules to keep in mind:

in the main function you must instantiate an AnsibleModule object with an argument specification.
you can access the Ansible task arguments using the module.params dictionary and use them to implement your logic.
the main function exits when either module.fail_json (in case of failure) or module.exit_json (in case of success) is called.

So given these rules, the main function signature will probably look like this:

1
2


def main() -> None:
 ...

6. The main guard

This is the last part and is the entry point of the module. It contains the code call that is executed when the module is called, either by Ansible when it executes the module on the target host or when we want to test the module locally. This part usually looks like this:

1
2


if __name__ == '__main__':
 main()

Now that we know how a module is structured, let’s try to implement a simple module ourselves.

Task 2 - Schrödingers Cat - Module specification

Let’s say for some reason we need a module schroedingers_cat which can determine the state of a cat on our hosts. We can implement it in the previously created directory as ./library/schroedingers_cat.py. By default, the module must return dead and alive as the state of the cat. However, if the force_box_open argument is set to true, the module should choose randomly between alive or dead.

Given the above requirements, try to implement the DOCUMENTATION, EXAMPLES and RETURN of the schroedingers_cat module.

Solution Task 1

First create the module file:

1

touch ./library/schroedingers_cat.py

Now, add these blocks and don’t forget the boilerplate code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


#!/usr/bin/python
# Copyright: (c) 2025, Your Name <your@email.ch>
# 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: schroedingers_cat
short_description: Determine the state of a cat
description:
 - Determine the state of the cat either by opening the box or assume that it is in a superposition state.
options:
 force_box_open:
 description: Open the box to determine the state of the cat.
 required: false
 type: bool
 default: false
author:
 - Your Name <your@email.ch>
'''

EXAMPLES = r'''
- name: Determine the state of a cat
 schroedingers_cat:
 force_box_open: true
 register: cat_state

- name: Determine the state of a cat without opening the box
 schroedingers_cat:
 register: cat_state

'''

RETURN = r'''
cat_state:
 description: The state of the cat
 type: str
 returned: always
 sample: 'alive'
'''

Task 2 - Schrödingers Cat - Implementing the module

Now let’s implement the main function of the schroedingers_cat module.

Keep in mind the rules for the main function mentioned above and don’t forget to call the function in the main guard.

Solution Task 2

First we must import the required python dependencies:

1
2
3


from ansible.module_utils.basic import AnsibleModule

import random

Now we can start the main function by creating the argument specification and instantiating an AnsibleModule object:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


def main() -> None:
 module_args_spec: dict = dict(
 force_box_open=dict(
 type="bool",
 default=False,
 required=False,
 )
 )

 module = AnsibleModule(argument_spec=module_args_spec)

The next step now would be to access the arguments using the module.params dictionary to implement the logic of the module.

1
2


 force_box_open: bool = module.params["force_box_open"]
 cat_state: str = random.choice(["alive", "dead"]) if force_box_open else "dead and alive"

Finally, we can return the result using the module.exit_json function:

1

 module.exit_json(cat_state=cat_state)

At the very last of the file we need to add the main guard where we call the main function:

1
2


if __name__ == "__main__":
 main()

Task 3 - Schrödingers Cat - Verifying the module

Now that we have the logic in place let’s verify the module. First we can test using ansible-doc if the module is detected correctly by ansible. If so we can then proceed with testing our module with an Ansible adhoc command.

Solution Task 3

First check using ansible-doc:

1

ansible-doc schroedingers_cat

If the module is detected correctly, we can then proceed with testing our module with Ansible adhoc commands:

1
2
3
4
5
6


$ ansible localhost -m schroedingers_cat
[WARNING]: No inventory was parsed, only implicit localhost is available
localhost | SUCCESS => {
 "cat_state": "dead and alive",
 "changed": false
}

or with the force_box_open argument:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


$ ansible localhost -m schroedingers_cat -a "force_box_open=true"
[WARNING]: No inventory was parsed, only implicit localhost is available
localhost | SUCCESS => {
 "cat_state": "dead",
 "changed": false
}
$ ansible localhost -m schroedingers_cat -a "force_box_open=true"
[WARNING]: No inventory was parsed, only implicit localhost is available
localhost | SUCCESS => {
 "cat_state": "alive",
 "changed": false
}

Running the module with the force_box_open argument should result in a random alive or dead state.

All done?

Can you verify your module in any other way? see Verifying your module

Docs: 12.4 Initializing a Collection

Mon, 01 Jan 0001 00:00:00 +0000

Ansible modules are packaged and published inside Ansible collections in order to be used. Therefore, we will start by learning how to initialize a collection. Since we have already set up our Python environment in the previous lab, we can start right away.

Task 1 - Creating the Collection

Create the training.labs collection in the current project directory /home/ansible/techlab/ansible-module-development using the ansible-creator tool.

Solution Task 1

1
2


pipenv shell
ansible-creator init collection training.labs ./training.labs

Task 2 - Set up the ansible development environment

With the collection created we can start working with its ansible development environment (ade). This tool installs our newly created collection inside our virtual environment in such a way that ansible can use it.

Can you find out how to use the ade install command to install the collection to your current pipenv?

Solution Task 2

To get the current virtualenv from pipenv you can use pipenv --venv. The output of this command can then be further used inside the ade install command as follows:

1
2


cd training.labs
ade install -e .\[test] --venv $(pipenv --venv)

Not also the -e flag is required to install the collection in editable mode. If you installed it in any other way, use ade uninstall training.labs and repeat the command above.

Task 3 - Verify the collection installation

How can you verify that the new collection is installed and can be used by ansible?

The newly created collection comes with a few sample plugins out of the box which for now we will use to verify the collection installation.

Solution Task 3

You can check the installation of your collection in the following ways:

Using the ade list command you should see your collection in the list.
Using the ansible-doc --list command you should see the sample modules that come with the collection (e.g. training.labs.sample_module).
Most important you should see the collection in the pipenv --venv folder (inside the lib/python3.1*/site-packages folder):
1

ls -lah $(pipenv --venv)/lib/python3.1*/site-packages/ansible_collections/training/labs
Here you can see that ade creates a symlink to the collection folder ./training.labs inside the ansible_collections folder.

Task 4 - Adding a new module

We will now proceed to add the schroedingers_cat module from the previous chapter to the collection.

Can you add it to the collection such that you can use it with the ansible-doc command using its fully qualified name training.labs.schroedingers_cat?

Solution Task 4

We must place the module inside the plugins/modules folder of the collection:

1

cp ~/techlab/ansible-module-development/library/schroedingers_cat.py ./training.labs/plugins/modules/schroedingers_cat.py

Now we can proceed to verify it:

1

ansible-doc training.labs.schroedingers_cat

All done?

Have a look at the file structure of the newly created collection in the training.labs folder. Try to understand the structure, you can use the Ansible Collection structure documentation to learn more about the structure.

Docs: 12.5 Testing Your Module

Mon, 01 Jan 0001 00:00:00 +0000

Since we now have our module inside our new collection we want to test it. For that the ansible tooling has a set of modules to help us with different kinds of testing.

Ansible content should be tested in three ways:

Sanity Testing - Mainly static code analysis of different kinds
Unit Testing - Testing the logic of you code
Integration Testing - Testing how you ansible content behaves when integrated with other ansible content

We will have a look at how to set up and create these kind of tests. But first let’s have a look on how these tests are executed.

Task 1 - tox-ansible

To perform tests on Ansible content tox alongside with the tox plugin tox-ansible is used. tox is a Python test-automation framework, which allows you to run tests in different environments. When we created the collection using the ansible-creator tool, it created a tox-ansible.ini file which we can use as a tox configuration.

In this file, we can configure what Python versions and Ansible versions to perform test against. This can be very powerful especially when running extensive CI pipelines. However, we will focus on our local Python and Ansible versions for now. Try to solve the following tasks:

Can you list all available tests?
What Python and Ansible versions are available on you lab server?
Can you configure the tox-ansible plugin to use your local Python and Ansible versions? (Use the tox ansible documentation)

Solution Task 1

With the pipenv activated and inside the collection directory run:
1

tox list --ansible -c tox-ansible.ini

You can find out which Python and Ansible versions are available by running:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


 $ python -V
 Python 3.12.5
 $ ansible --version
 ansible [core 2.18.6]
 config file = /home/ansible/techlab/ansible-module-development/ansible.cfg
 configured module search path = ['/home/ansible/techlab/ansible-module-development/library']
 ansible python module location = /home/ansible/.local/share/virtualenvs/ansible-module-development-J9Af2H_I/lib/python3.12/site-packages/ansible
 ansible collection location = /home/ansible/.ansible/collections:/usr/share/ansible/collections
 executable location = /home/ansible/.local/share/virtualenvs/ansible-module-development-J9Af2H_I/bin/ansible
 python version = 3.12.5 (main, Apr 2 2025, 00:00:00) [GCC 11.5.0 20240719 (Red Hat 11.5.0-5)] (/home/ansible/.local/share/virtualenvs/ansible-module-development-J9Af2H_I/bin/python)
 jinja version = 3.1.6
 libyaml = True

You can configure tox-ansible to use your local Python and Ansible versions by skipping all versions that do not match your local Python and Ansible versions. The following lines should do the trick:
1 2 3 4 5 6 7 8 9

[ansible] skip = py3.10 py3.11 py3.13 2.16 2.17 devel milestone

Task 2 - Sanity Testing our collection

Let’s try to run sanity tests against our collection. List the available sanity tests again and choose to run the sanity tests.

In the test output you will encounter some issues regarding the sample plugins, feel free to either remove these plugins or ignore them.

Does the schroedingers_cat plugin pass the sanity tests?

Try to fix all the tests.

Solution Task 2

You can execute a specific sanity test by running:

1

tox -e sanity-py3.12-2.18 --ansible --conf tox-ansible.ini

Those plugins can be removed:

1
2
3


rm plugins/test/sample_test.py
rm plugins/action/sample_action.py
rm plugins/action/sample_*.py

Task 3 - Unit Testing our collection

Unit tests can be run similarly to sanity tests but with the unit environment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


$ tox -e unit-py3.12-2.18 --ansible --conf tox-ansible.ini
....

2 workers [1 item]
scheduling tests via LoadScheduling

tests/unit/test_basic.py::test_basic
[gw0] [100%] PASSED tests/unit/test_basic.py::test_basic

================================================ 1 passed in 0.40s ================================================
 unit-py3.12-2.18: OK (74.18=setup[45.34]+cmd[0.00,0.13,27.87,0.02,0.82] seconds)
 congratulations :) (74.27 seconds)

As you can see from the output of this command there are already some basic tests present in the collection. We will ignore them for now and focus on writing our own tests against our collection to make sure our module works as expected.

The Ansible Community Documentation has an extensive documentation page about unit testing modules that you can find here. Keep this page in mind since it may come in handy as a reference for the following tasks. It may also be helpful if you are not familiar with unit testing and want to learn more on what unit tests are and why we need them.

For now, we will start by creating a test file for the schroedingers_cat module in the tests/unit/plugins/modules directory and adding some test cases in it. In this lab we will use pytest style test cases.

Can you implement the following unit test cases?

The module should always return a cat_state on exit.
The module should always return a cat state of dead and alive when the force_box_open argument is set to False (default).
The module should always return a cat state of alive or dead when the force_box_open argument is set to True.

Solution Task 3

First create the unit test file:

1
2
3
4


cd training.labs
mkdir -p tests/unit/plugins/modules
touch tests/unit/plugins/{,modules/}__init__.py
touch tests/unit/plugins/modules/test_schroedingers_cat.py

To write isolated unit tests we will need some of the utilities introduced in the Ansible Community Documentation. First we need to address the question of how we can control which arguments our module will be called with in the unit test.

The set_module_args function from the documentation can be used to set the arguments that will be passed to the module:

1
2
3
4
5
6
7


from ansible.module_utils import basic
from ansible.module_utils.common.text.converters import to_bytes

def set_module_args(args):
 """prepare arguments so that they will be picked up during module creation"""
 args = json.dumps({'ANSIBLE_MODULE_ARGS': args})
 basic._ANSIBLE_ARGS = to_bytes(args)

With this approach we leverage a global variable which ansible uses to store the passed arguments. Then we can set the arguments to the module by calling the set_module_args function in the test cases.

The second issue we need to address is to verify the termination status of the module. It either will call the exit_json function or the fail_json function. Using pytest fixtures, we can mock the AnsibleModule functions:

1
2
3
4
5
6
7
8


from unittest.mock import patch, MagicMock

import pytest

@pytest.fixture
def mock_exit_json():
 with patch('ansible.module_utils.basic.AnsibleModule.exit_json', new=MagicMock()) as mock:
 yield mock

Now let’s implement the unit tests for the cases mentioned above:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


from ansible_collections.training.labs.plugins.modules import schroedingers_cat

def test_schroedingers_cat_returns_cat_state(mock_exit_json: MagicMock) -> None:
 """
 Check that the module returns a cat state.
 """
 set_module_args({})
 schroedingers_cat.run_module()

 mock_exit_json.assert_called_once()
 assert "cat_state" in mock_exit_json.call_args.kwargs


def test_schroedingers_cat_returns_dead_and_alive_when_force_box_open_is_false(mock_exit_json: MagicMock) -> None:
 """
 Check that the module returns dead and alive when force_box_open is false.
 """
 set_module_args({'force_box_open': False})
 schroedingers_cat.run_module()

 mock_exit_json.assert_called_once()
 assert mock_exit_json.call_args.kwargs['cat_state'] == 'dead and alive'


def test_schroedingers_cat_returns_alive_or_dead_when_force_box_open_is_true(mock_exit_json: MagicMock) -> None:
 """
 Check that the module returns alive or dead when force_box_open is true.
 """
 set_module_args({'force_box_open': True})
 schroedingers_cat.run_module()

 mock_exit_json.assert_called_once()
 assert mock_exit_json.call_args.kwargs['cat_state'] in ['alive', 'dead']

Now we can run the unit tests using tox just like we did for the sanity tests:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


$ tox -e unit-py3.13-2.18 --ansible -c tox-ansible.ini
...
============================================== test session starts ================================================
...

tests/unit/plugins/modules/test_schroedingers_cat.py::test_schroedingers_cat_returns_cat_state
tests/unit/plugins/modules/test_schroedingers_cat.py::test_schroedingers_cat_returns_dead_and_alive_when_force_box_open_is_false
[gw1] [ 33%] PASSED tests/unit/plugins/modules/test_schroedingers_cat.py::test_schroedingers_cat_returns_dead_and_alive_when_force_box_open_is_false
[gw0] [ 66%] PASSED tests/unit/plugins/modules/test_schroedingers_cat.py::test_schroedingers_cat_returns_cat_state
tests/unit/plugins/modules/test_schroedingers_cat.py::test_schroedingers_cat_returns_alive_or_dead_when_force_box_open_is_true
[gw0] [100%] PASSED tests/unit/plugins/modules/test_schroedingers_cat.py::test_schroedingers_cat_returns_alive_or_dead_when_force_box_open_is_true

================================================ 3 passed in 0.44s ================================================
 unit-py3.13-2.18: OK (4.81=setup[0.04]+cmd[0.00,0.23,3.78,0.01,0.74] seconds)
 congratulations :) (4.88 seconds)

Task 4 - Integration Tests

As you saw in the available tox environments we have integration-py3.12-2.18 environment. Let’s have a look at what this environment is doing.

Looking inside the tests directory we can see that besides the unit directory that we saw earlier there is a integration directory. In this directory we have a subdirectory targets in which we can write our integration tests in form of ansible roles. tox will then use these roles to run them inside molecule test scenarios. molecule is a test framework for Ansible content.

So we might go ahead and write a role in the targets directory called schroedingers_cat. In this role we will write our integration tests by calling our module, registering its output and inspecting the result using the assert module.

Try to test the following cases:

Calling the module with force_box_open set to False (default) should result in a cat state of dead and alive.
Calling the module with force_box_open set to True should result in a cat state of alive or dead.

Try to verify that by running the role in the integration-py3.12-2.18 environment. While doing so you might at first encounter an error regarding an integration_hello_world test failing. Can you figure out how to set up molecule in the extensions directory to make run your new test instead of the hello_world test?

Solution Task 4

First you need to create a molecule scenario in the extensions/molecule directory. You can do that by renaming the integration_hello_world scenario to integration_schroedingers_cat.

Next you need to create a role in the targets directory called schroedingers_cat. Inside this role you can create a file called tasks/main.yml and add write the test cases, for example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


- name: Test schroedingers_cat without force open box
 block:
 - name: Test schroedingers_cat without force open box
 training.labs.schroedingers_cat:
 register: no_force_result

 - name: Assert that the cat state is 'dead and alive'
 ansible.builtin.assert:
 that:
 - no_force_result.cat_state == 'dead and alive'

- name: Test schroedingers_cat with force open box
 block:
 - name: Test schroedingers_cat with force open box
 training.labs.schroedingers_cat:
 force_box_open: true
 register: force_result

 - name: Assert that the cat state is 'dead' or 'alive'
 ansible.builtin.assert:
 that:
 - force_result.cat_state in ['dead', 'alive']

Run the role in the integration-py3.12-2.18 environment and verify that the tests pass.

All done?

Try reading up on molecule. What is a scenario? What is a test sequence? What is being configured in the molecule.yml?

Docs: 12.6 Tracking State in a Custom Module

Mon, 01 Jan 0001 00:00:00 +0000

In this lab, you will extend the schroedinger_cat example module to track the cat’s state on every host by writing it to a file in /tmp/.cat_state.txt. You will also add support for check mode and ensure that the module always provides a diff when run with --diff.

Task 1 - Write Cat State to a file

Modify the module so that it writes the current cat state (“alive” or “dead”) to /tmp/.cat_state whenever it runs (we will handle the check mode later).

Verify this behaviour in the integration tests from the previous lab.

Solution Task 1

Let’s have a look at one possible solution. We can start by having a look at the run_module function and see how the new program flow could look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


from typing import Optional


def run_module() -> None:
 module_args_spec: dict = dict(
 force_box_open=dict(
 type="bool",
 default=False,
 required=False,
 )
 )

 module = AnsibleModule(argument_spec=module_args_spec)
 force_box_open: bool = module.params["force_box_open"]

 if not force_box_open:
 # If the box is not opened, the cat is in a superposition state
 module.exit_json(cat_state="dead and alive")

 previous_cat_state: Optional[str] = _get_previous_cat_state()
 new_cat_state: str = random.choice(["alive", "dead"])
 changed: bool = False

 if previous_cat_state != new_cat_state or previous_cat_state is None:
 changed = True
 _write_cat_state(new_cat_state)

 module.exit_json(cat_state=new_cat_state, changed=changed)

Now given this top level function, let’s have a look at how the _write_cat_state and _get_previous_cat_state function could look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


from typing import Optional


CAT_STATE_FILE_PATH: str = "/tmp/.cat_state.txt"


def _get_previous_cat_state() -> Optional[str]:
 """
 Get the previous cat state from the file.
 """
 try:
 with open(CAT_STATE_FILE_PATH, "r") as f:
 return f.read().strip()
 except (IOError, FileNotFoundError):
 return None


def _write_cat_state(cat_state: str) -> None:
 """
 Write the cat state to the file.
 """
 with open(CAT_STATE_FILE_PATH, "w") as f:
 f.write(cat_state)

Your integration tests could look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


---

- name: Test schroedingers_cat without force open box
 block:
 - name: Test schroedingers_cat without force open box
 training.labs.schroedingers_cat:
 register: no_force_result

 - name: Assert that the cat state is 'dead and alive' and not changed
 ansible.builtin.assert:
 that:
 - no_force_result.cat_state == 'dead and alive'
 - not no_force_result.changed

 - name: Get cat state file stats
 ansible.builtin.stat:
 path: "/tmp/.cat_state.txt"
 register: file_result

 - name: Assert that the file has not been created since the box has not been opened
 ansible.builtin.assert:
 that:
 - not file_result.stat.exists

- name: Test schroedingers_cat with force open box
 block:
 - name: Test schroedingers_cat with force open box
 training.labs.schroedingers_cat:
 force_box_open: true
 register: force_result

 - name: Assert that the cat state is 'dead' or 'alive'
 ansible.builtin.assert:
 that:
 - force_result.cat_state in ['dead', 'alive']

 - name: Get cat state file stats
 ansible.builtin.stat:
 path: "/tmp/.cat_state.txt"
 register: file_result

 - name: Assert that the file has been created since the box has been opened
 ansible.builtin.assert:
 that:
 - file_result.stat.exists

Task 2 - Implement a molecule cleanup playbook

Running the previous integration tests will create a file in the user’s home directory. So when re-running the tests, they will fail. Let’s write a molecule cleanup playbook to remove it.

Can you figure out how to add a playbook in the extensions/molecule/ directory that removes the file before and after each run?

Solution Task 2

For instance, you could create a playbook in the extensions/molecule/integration_schroedingers_cat scenario called cleanup_cat_state.yml. The playbook could look like this:

1
2
3
4
5


---
- name: Remove cat state file
 file:
 path: "/tmp/.cat_state.txt"
 state: absent

Now configure it in the molecule.yml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


---
...
provisioner:
 ...
 playbooks:
 cleanup: ./cleanup_cat_state.yml
 converge: ../utils/playbooks/converge.yml
 destroy: ./cleanup_cat_state.yml
 prepare: ./cleanup_cat_state.yml
...

Now re-run the integration tests and make sure they pass.

Task 3 - Implement Check Mode Support

The next feature we want to support in our module is the ansible check mode.

Can you figure out how to implement it in our existing module?

Don’t forget to test it!

Solution Task 3

To support the check mode in our module we need to enable it when instantiating the module:

1
2
3


 ...
 module = AnsibleModule(argument_spec=module_args_spec, supports_check_mode=True)
 ...

Next we need to prevent creating a file or writing to it in check mode. One solution could be in the run_module function to not call the _write_cat_state function in check mode:

1
2
3
4
5
6


 ...
 if previous_cat_state != new_cat_state or previous_cat_state is None:
 changed = True
 if not module.check_mode:
 _write_cat_state(new_cat_state)
 ...

Now to test it we can add a new block to the integration tests. To ensure the file is not created by any other block, go ahead and add the following block before the Test schroedingers_cat with force open box block:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23



- name: Test schroedingers_cat with force open box in check mode
 block:
 - name: Test schroedingers_cat with force open box
 training.labs.schroedingers_cat:
 force_box_open: true
 check_mode: true
 register: force_result

 - name: Assert that the cat state is 'dead' or 'alive'
 ansible.builtin.assert:
 that:
 - force_result.cat_state in ['dead', 'alive']

 - name: Get cat state file stats
 ansible.builtin.stat:
 path: "/tmp/.cat_state.txt"
 register: file_result

 - name: Assert that the file has not been created since it ran in check mode
 ansible.builtin.assert:
 that:
 - not file_result.stat.exists

Task 4 - Always Return a Diff Value

Ensure the module always returns a diff value in the result, showing the previous and new state whenever a change occurs. This enables --diff mode support.

To do so we need to add a diff key to the result, containing a dictionary with a before and after key.

Go ahead, implement and test it!

Solution Task 3

We could implement it like this in the run_module function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


 ...
 changed: bool = False
 diff: dict = {}

 if previous_cat_state != new_cat_state or previous_cat_state is None:
 changed = True
 diff = {
 "before": previous_cat_state ,
 "after": new_cat_state,
 }
 if not module.check_mode:
 _write_cat_state(new_cat_state)

 module.exit_json(cat_state=new_cat_state, changed=changed, diff=diff)

...

Test it by adding a few checks to the assertions in the integration tests. For example, we expect the diff to be present when the state of the cat is changed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10



- name: Test schroedingers_cat with force open box
 block:
 ...

 - name: Assert a diff exists when the cat state is changed
 ansible.builtin.assert:
 that:
 - force_result.diff
 when: force_result.changed

All done?

Can you make the state file path configurable via a module parameter?

Docs: 12.7 Module Utils

Mon, 01 Jan 0001 00:00:00 +0000

In this short lab we will have a look on how to move reusable code from modules into module utils.

Task 1 - Create a Module Utils for file handling

In the last lab, we created a simple module that allows us to track the cat’s state on every host by writing it to a file in /tmp/.cat_state.txt. To do so we wrote two functions in the module to write and read the cat state from the file.

Let’s create a module util for file handling operations called state_file_utils.py and move the functions there.

Solution Task 1

Create the moduel_utils/state_file_utils.py file with the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


# Copyright: (c) 2025, Your Name <your@email.ch>
# 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

from typing import Optional

CAT_STATE_FILE_PATH: str = "/tmp/.cat_state.txt"


def read_cat_state() -> Optional[str]:
 """
 Get the previous cat state from the file.
 """
 try:
 with open(CAT_STATE_FILE_PATH, "r") as f:
 return f.read().strip()
 except (IOError, FileNotFoundError):
 return None


def write_cat_state(cat_state: str) -> None:
 """
 Write the cat state to the file.
 """
 with open(CAT_STATE_FILE_PATH, "w") as f:
 f.write(cat_state)

Now import it in the training.labs.schroedingers_cat module and update the code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


...

from ansible.module_utils.basic import AnsibleModule

from ansible_collections.training.labs.plugins.module_utils.state_file_utils import (
 read_cat_state,
 write_cat_state,
)

import random
from typing import Optional


def run_module() -> None:
 ...
 previous_cat_state: Optional[str] = read_cat_state()
 ...
 if previous_cat_state != new_cat_state or previous_cat_state is None:
 ...
 if not module.check_mode:
 write_cat_state(new_cat_state)
...

All done?

Can you add unit tests to the module utils?

Ansible Training – 12. Ansible Module Development

Docs: 12.1 Ansible Module Development - Basics

Task 1

All done?

Docs: 12.2 Environment Setup

Why Use Virtual Environments?

Note

Introducing pipenv

Task 1

Task 2

Task 3

Task 4

Note on Version-Specific Dependency Installation

Task 5

Deactivating the Environment

All done?

Docs: 12.3 Creating a Local Module

Setup

Ansible Module Structure

1. Some boilerplate code

2. The DOCUMENTATION block

3. The EXAMPLES block

4. The RETURN block

5. The main function

6. The main guard

Task 2 - Schrödingers Cat - Module specification

Task 2 - Schrödingers Cat - Implementing the module

Task 3 - Schrödingers Cat - Verifying the module

All done?

Docs: 12.4 Initializing a Collection

Task 1 - Creating the Collection

Task 2 - Set up the ansible development environment

Task 3 - Verify the collection installation

Task 4 - Adding a new module

All done?

Docs: 12.5 Testing Your Module

Task 1 - tox-ansible

Task 2 - Sanity Testing our collection

Task 3 - Unit Testing our collection

Task 4 - Integration Tests

All done?

Docs: 12.6 Tracking State in a Custom Module

Task 1 - Write Cat State to a file

Task 2 - Implement a molecule cleanup playbook

Task 3 - Implement Check Mode Support

Task 4 - Always Return a Diff Value

All done?

Docs: 12.7 Module Utils

Task 1 - Create a Module Utils for file handling

All done?

Introducing `pipenv`

2. The `DOCUMENTATION` block

3. The `EXAMPLES` block

4. The `RETURN` block