Lab Guide: Using the Ansible Development Environment tool

A guide to exploring what ansible-creator and ade (Ansible Dev Environment) can do for your collection.

Lab briefing

Ansible Dev Environment (ade) is a management tool for Ansible content development that provides isolated workspaces for development. ade manages virtual environments, collection installation and removal, and Python dependency resolution to ensure consistent, reproducible development environments.

ade provides comprehensive collection development environment management by:

Creating isolated virtual environments
Installing and removing collections with full dependency tracking
Resolving and installing collection Python dependencies from requirements.txt and test-requirements.txt
Installing collections in editable mode with symlinks for active development
Managing development dependencies like ansible-dev-tools
Providing configurable workspace isolation

In this challenge, you will explore the content that was automatically generated for the collection you just created and learn how to customize your requirements using ade.

Learning objectives

After completing this module, you will be able to:

Customize the galaxy.yml metadata for your collection
Use ade to install and manage collection dependencies
Understand how ade tracks Python and system-level requirements

Scaffolded collection files in the Explorer view

Lab guide: Hands-on tasks

You will now set up your Ansible development environment, check the scaffolded collection content, and add a dependency to your collection’s galaxy.yml to see how the new ade tool helps manage it.

Task 1: Activate your Ansible Development Environment

First, you will activate the Python virtual environment (.venv) that ansible-creator built for you.

View the generated files in the left sidebar of VS Code. You can see the list of all files generated by Ansible Creator.
Open the galaxy.yml file by clicking on it in the left sidebar.
Activate the Python virtual environment by clicking the banner that reads Python: Select Interpreter in the bottom status bar of VS Code. From the dropdown menu that appears at the top, select the recommended option: Python 3.11.11 ('.venv': venv).

This is a convenient alternative to manually running source .venv/bin/activate in the terminal.

Task 2: Add collection dependencies

The Ansible Development Environment (ade) tool helps manage dependencies for your collections.

Explore the scaffolded files. Take a moment to explore the content of these auto-generated files (do not edit them yet):
- .gitignore: This is pre-loaded with settings to ignore common temporary files, making your Git commits cleaner.
- test-requirements.txt: This already includes the Python dependencies required for running tests with Molecule.
- galaxy.yml: This is the identity card of an Ansible collection. It describes what the collection is, who owns it, how it should be discovered and how it should be trusted and consumed.
Open galaxy.yml by clicking on it in the file explorer sidebar: We will replace the default values, this directly affects how your content is indexed, validated, searched and governed.
```
namespace: "mynamespace"
name: "mycollection"
version: 1.0.0
readme: README.md
authors:
  - your name <example@domain.com>

description: your collection description
license_file: LICENSE

# TO-DO: update the tags based on your content type
tags: ["linux", "tools"]
```
You will notice the namespace and name have already been auto-filled correctly, they are immutable and changing them is like creating a new collection. The version is important as well as it’s used for dependency constraints, version resolution and upgrade/downgrade logic.

You will also notice the readme and license_file are pointing to existing files, we can leave those as they are. You can modify the scaffolded README.md and LICENSE files if you wish to change those.

We will replace the following fields:
- your name <example@domain.com> in the authors: section with your own name and email. This is used for ownership attribution, support and maintenance.
- your collection description in the description: section with mycowsay collection This is used for the search results summaries in Galaxy and Automation Hub, as well as the collection landing page.
- the tags: These tags are used in Galaxy and Automation Hub for discoverability and they are specially important in large catalogs. Consider the purpose of your collection for them. The available categories are application, cloud, database, eda, infrastructure, linux, monitoring, networking, security, storage, tools, windows.
Let’s add a requirement to see ade in action: Modify the dependencies: block to add ansible.posix. This is used for automatic dependency installation and compatibility validation. The result should look like this:
```
dependencies:
  "ansible.utils": "*"
  "ansible.posix": "*"
```
+ The asterisk (*) mean latest version. This could be a pinned version (1.5.0) as well or even a greater (>=) or smaller (<=) than.
Save the file using the menu (File → Save) or by pressing Ctrl + S (Cmd + S on Mac).

Task 3: Check Ansible Development Tools versions

Let’s check the versions of the Ansible development tools installed in your environment.

Open the Terminal in VS Code from the top menu by clicking Terminal → New Terminal

Check the tool versions by running the following command to see the versions of all installed tools:

adt --version

Notice the command is adt (Ansible Development Tools). In the next task, you will use ade (Ansible Development Environment). These are different tools.

The output should look similar to this:

(.venv) [rhel@vscode mycollection]$ adt --version
ansible-builder                          3.1.1
ansible-core                             2.19.5
ansible-creator                          25.12.0
ansible-dev-environment                  25.12.2
ansible-dev-tools                        26.1.0
ansible-lint                             26.1.1
ansible-navigator                        26.1.1
ansible-sign                             0.1.4
molecule                                 25.12.0
pytest-ansible                           25.12.0
tox-ansible                              26.1.0

Versions might differ, don’t worry. The list above is an example.

Task 4: Manage dependencies with `ade`

Now you will use ade to install the dependencies you declared in galaxy.yml.

Install the collection dependencies by running the following command in the VS Code terminal. This will install your collection and its dependencies into the virtual environment.

Notice the -e . with a dot at the end of the command. This tells ade to perform an editable (the -e) install, creating a link from the virtual env into your working directory (the .).

ade install -e .

The output should look like this:

(.venv) [rhel@vscode mycollection]$ ade install -e .
    Note: Installed collections include: ansible.posix, ansible.utils, and
          mynamespace.mycollection
 Warning: No git repository found, using heuristic filtering
    Note: Note: If you add new root-level directories or files to your
          collection, you will need to re-run 'ade install -e .' to include them in the editable install.
    Note: All python requirements are installed.
    Note: All required system packages are installed.

Check the dependency tree by running ade tree -v to see the installed dependencies.
Add another collection dependency by going back to the galaxy.yml file and adding "ansible.netcommon": "*" to the dependencies: list. Save the file. The result should look like this:
```
dependencies:
  "ansible.utils": "*"
  "ansible.posix": "*"
  "ansible.netcommon": "*"
```

Attempt to re-run the installation by running the ade install -e . command again in the terminal.

The command will fail. Don’t panic! This is expected. ade has detected that ansible.netcommon requires certain system-level packages that are not installed on your workstation’s operating system. image::vscode-devtools-netcommon-system-packages.png[Command failure showing missing system packages,link=self,window=blank, opts="border"]

Install the system dependencies by running the following command in the VS Code terminal to install the missing OS packages:
```
sudo dnf install -y python3-cffi python3-cryptography python3-lxml python3-pycparser
```
Re-run the ade installation. Now, run ade install -e . one more time in the terminal. It should succeed.
Check the new dependency tree. Finally, run ade tree -v again. The output will now show that ade has successfully added the ansible.netcommon collection to your environment, along with its Python requirements.

Remember the "Install collection from source code (editable mode)" option you selected during the Collection creation wizard? That option used ade install -e to automatically create the virtual environment (.venv) that you are using now.

Next steps

You have successfully explored how Ansible Dev Tools (adt) and Ansible Dev Environment (ade) work. Please click the Next button below to proceed to the next module.