How to Track Ansible Project Dependencies with Requirement Files

Ansible is often called a "batteries included" IT automation tool, meaning that many popular collections are included by default when you install the Ansible package from PyPi. However, some Ansible projects need to use a collection or role provided by a vendor, such as the Palo Alto PAN-OS or Oracle Cloud Infrastructure collections. Installing these modules in your development environment is easy, but you need to track these dependencies as part of the Ansible project so that other developers know to install them.

Ansible Galaxy, which is a software repository maintained by Red Hat for Ansible collections and roles, lets us track the dependencies for our project through a requirements.yml file. Furthermore, we can easily install dependencies using Ansible Galaxy’s command line.

Start Learning Ansible Today

If you’re interested in learning how to leverage Ansible, CBT Nuggets offers Red Hat Certified Ansible Network Automation and Automating Networks with Ansible Online training courses. 

If you're not a CBT Nuggets subscriber, sign up for a one-week no-strings-attached trial to explore these courses and many others for roles such as network engineers, systems administrators, and DevOps engineers.

Getting Oriented with Our Project

First, let’s briefly review the directory where our Ansible project is stored using the ls -lh command.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ls -lh
total 12K
-rw-rw-r-- 1 christopher christopher   77 Oct  1 14:53 ansible.cfg
-rw-rw-r-- 1 christopher christopher    0 Oct  1 14:56 playbook.yaml
-rw-rw-r-- 1 christopher christopher   15 Oct  1 14:53 requirements.txt
drwxrwxr-x 5 christopher christopher 4.0K Oct  1 14:53 venv

As you can see, we have a requirements.txt file. The contents of this file indicate Ansible 6.4.0 should be installed in this project as shown by the cat requirements.txt command.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ cat requirements.txt 
ansible==6.4.0

The pip list command confirms that Ansible 6.4.0 is installed within our Python virtual environment, which is currently activated as indicated by the (venv) string prepended to our shell’s prompt.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ pip list
Package      Version
------------ -------
ansible      6.4.0
ansible-core 2.13.4
cffi         1.15.1
cryptography 38.0.1
Jinja2       3.1.2
MarkupSafe   2.1.1
packaging    21.3
pip          22.0.2
pycparser    2.21
pyparsing    3.0.9
PyYAML       6.0
resolvelib   0.8.1
setuptools   59.6.0

The cat ansible.cfg command indicates that the only Ansible configuration change specific to our project at the moment is that the Python 3 binary within our virtual environment is used as Ansible’s Python interpreter.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ cat ansible.cfg 
[defaults]
ansible_python_interpreter=/venv/bin/python3

Creating the Requirements File

In the root of our Ansible project, we will create a new file named requirements.yaml with the touch requirements.yaml command that will serve as the requirements file for our Ansible project. We will then confirm it was created with the ls -lh requirements.yaml command.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ touch requirements.yaml
(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ 
(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ls -lh requirements.yaml 
-rw-rw-r-- 1 christopher christopher 0 Oct  1 15:13 requirements.yaml

Note: The file extension for the requirements file can be either .yaml or .yml - either will work without issue!

As the name suggests, this is a YAML file that can contain two keys:

• collections - A list of collections to install from Ansible Galaxy

• roles - A list of roles to install from Ansible Galaxy

To start out with, the contents of our requirements.yaml file should look something like this:

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ cat requirements.yaml 
---
collections:
roles:

You can then add the names of your dependencies under the relevant type. For example, if I need to track the Palo Alto PAN-OS and Oracle Cloud Infrastructure collections, I would modify the requirements.yaml file to read as follows:

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ cat requirements.yaml 
---
collections:
  - paloaltonetworks.panos
  - oracle.oci
roles:

Tracking roles is just as easy! For example, if you need to track Jeff Geerling’s Docker role, I would add it under the roles key as shown below.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ cat requirements.yaml 
---
collections:
  - paloaltonetworks.panos
  - oracle.oci
roles:
  - geerlingguy.docker

Installing Ansible Dependencies from Requirements Files

Now that our requirement file has been created and populated, we can use the ansible-galaxy install -r requirements.yaml command to install dependencies from the requirement file.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ansible-galaxy install -r requirements.yaml 
Starting galaxy role install process
- downloading role 'docker', owned by geerlingguy
- downloading role from https://github.com/geerlingguy/ansible-role-docker/archive/6.0.0.tar.gz
- extracting geerlingguy.docker to /home/christopher/.ansible/roles/geerlingguy.docker
- geerlingguy.docker (6.0.0) was installed successfully
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://galaxy.ansible.com/download/paloaltonetworks-panos-3.0.0.tar.gz to /home/christopher/.ansible/tmp/ansible-local-3940jisn5p2f/tmpgraiabxw/paloaltonetworks-panos-3.0.0-5v_9l1y4
Downloading https://galaxy.ansible.com/download/oracle-oci-3.4.0.tar.gz to /home/christopher/.ansible/tmp/ansible-local-3940jisn5p2f/tmpgraiabxw/oracle-oci-3.4.0-zdg3xfwa
Installing 'paloaltonetworks.panos:3.0.0' to '/home/christopher/.ansible/collections/ansible_collections/paloaltonetworks/panos'
paloaltonetworks.panos:3.0.0 was installed successfully
Installing 'oracle.oci:3.4.0' to '/home/christopher/.ansible/collections/ansible_collections/oracle/oci'
oracle.oci:3.4.0 was installed successfully

We can then use the ansible-galaxy collection list and ansible-galaxy role list commands to validate that specific collections or roles are properly installed in our Ansible environment.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ansible-galaxy collection list paloaltonetworks.panos

# /home/christopher/.ansible/collections/ansible_collections
Collection             Version
---------------------- -------
paloaltonetworks.panos 3.0.0  
(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ansible-galaxy collection list oracle.oci

# /home/christopher/.ansible/collections/ansible_collections
Collection Version
---------- -------
oracle.oci 3.4.0  
(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ansible-galaxy role list geerlingguy.docker
# /home/christopher/.ansible/roles
- geerlingguy.docker, 6.0.0

Tracking Specific Versions of Dependencies

By default, Ansible Galaxy will install the latest version of a collection or role that is available in the Ansible Galaxy repository. However, you sometimes may need to track a specific version of a dependency in order for your Ansible project to work as expected. For example, there may be a software bug or a breaking change in the latest version of a collection or role that breaks the Ansible automation in your project.

To work around this, you can track a specific version or set of versions for a dependency within the requirements file by specifying both the name and version key-value pairs under the collections or roles keys of the requirements file. An example of this is shown below, where version 2.10.2 of the Palo Alto PAN-OS collection is tracked.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ cat requirements.yaml 
---
collections:
  - name: paloaltonetworks.panos
    version: 2.10.2
  - oracle.oci
roles:
  - geerlingguy.docker

Previously, the 3.0.0 version of the Palo Alto PAN-OS collection was installed. We can use the ansible-galaxy collection install -r requirements.yaml command to re-analyze all collection dependencies installed and install the 2.10.2 version of the collection instead.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ansible-galaxy collection install -r requirements.yaml
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://galaxy.ansible.com/download/paloaltonetworks-panos-2.10.2.tar.gz to /home/christopher/.ansible/tmp/ansible-local-4168vq5yo24y/tmpu9dw2025/paloaltonetworks-panos-2.10.2-4_2kah3n
'oracle.oci:3.4.0' is already installed, skipping.
Installing 'paloaltonetworks.panos:2.10.2' to '/home/christopher/.ansible/collections/ansible_collections/paloaltonetworks/panos'
paloaltonetworks.panos:2.10.2 was installed successfully

The ansible-galaxy collection list paloaltonetworks.panos command confirms that version 2.10.2 of the Palo Alto PAN-OS collection is now installed.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ansible-galaxy collection list paloaltonetworks.panos

# /home/christopher/.ansible/collections/ansible_collections
Collection             Version
---------------------- -------
paloaltonetworks.panos 2.10.2

You can also specify a range of versions of a collection or role that your Ansible project is dependent on through the following identifiers:

• *: Install the most recent version of the dependency. This is the default value of the version key.

• ==: Install the exact version of the dependency.

• !=: Install a version of the dependency not equal to the version specified.

• >=: Install a version of the dependency greater than or equal to the version specified.

• >: Install a version of the dependency greater than the version specified.

• <=: Install a version of the dependency less than or equal to the version specified.

• <: Install a version of the dependency less than the version specified.

For example, let’s say the 2.10.0 version of the Palo Alto PAN-OS collection introduced a new module your Ansible automation uses, but the 3.0.0 version of the same collection introduced changes that breaks your Ansible automation. An example of range identifiers that meet these requirements is shown below.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ cat requirements.yaml 
---
collections:
  - name: paloaltonetworks.panos
    version: ">=2.10.0,<3.0.0"
  - oracle.oci
roles:
  - geerlingguy.docker

We can use the ansible-galaxy collection install -r requirements.yaml command to re-analyze our collection dependencies and install a version of the Palo Alto PAN-OS collection that meets our requirements, which is the 2.10.2 version.

(venv) christopher@ubuntu-playground:~/Ansible/ansible-project$ ansible-galaxy collection install -r requirements.yaml
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://galaxy.ansible.com/download/paloaltonetworks-panos-2.10.2.tar.gz to /home/christopher/.ansible/tmp/ansible-local-441167y5963t/tmpny1k4box/paloaltonetworks-panos-2.10.2-_g4zb0ix
'oracle.oci:3.4.0' is already installed, skipping.
Installing 'paloaltonetworks.panos:2.10.2' to '/home/christopher/.ansible/collections/ansible_collections/paloaltonetworks/panos'
paloaltonetworks.panos:2.10.2 was installed successfully

Final Thoughts

Now that the dependencies for your Ansible project are tracked through a requirements file, you can commit the requirements file to your version control (such as git or SVN) so that other members of your network or systems automation team can work from the same set of dependencies. 

This improves the developer experience, reduces the chance of dependency-based software bugs leaking into your automation, and sets your Ansible project up for success if you adopt Continuous Integration and Continuous Deployment (CI/CD) pipelines.