12.2 Ansible Module Development - Environment Setup

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 activiation 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

If you don’t have pipenv installed yet, you can install it globally using pip (which is usually installed with your Python distribution):

1
2
dnf install python3-pip
pip install 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 install
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.2.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.2.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.2.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?