AWX And Requirements

Overview

This article provides information and instructions in the use of the requirements.y[a]ml and requirements.txt file when running playbooks from AWX or Ansible Automation Platform (AAP).

Galaxy Collections and Roles

When running ansible on the command line interface (CLI), you may need to install a Galaxy Collection or Role for a task that the default ansible collections and roles don’t provide. It’s a positive feature of Ansible that it’s extendable.

You can view which collections and roles are installed by using the ansible-galaxy commands. For more information, pass the -h flag.

ansible-galaxy collection list
ansible-galaxy role list

Use the -p flag to indicate the installation is in a non-standard location. For example, in the automation container in AWX, ansible collections are located in the /runner/requirements_collections directory and not in the .ansible directory.

You’ll run the ansible-galaxy command to install the needed collection. For example, for vmware, you’d run the following command.

ansible-galaxy collection install vmware.vmware

For a role, you’d run the following command.

ansible-galaxy role install geerlingguy.docker

If you need to make sure another maintainer of your playbooks has the proper collections and roles installed before running the playbooks, you can list them in a README.md file and have them manually install them, or simply create a requirements.yaml (or .yml; both work) file.

For the CLI, there are three places where the requirements.yaml file can be located.

[project]/requirements.yaml
[project]/collections/requirements.yaml
[project]/roles/requirements.yaml

When I ran the playbook using a galaxy collection and the requirements.yaml file was in the roles directory, it failed to locate the collection.

The requirements.yaml file has several available parameters. See the documentation for all the details. This is a basic requirements.yaml file.

---
collections:
  - vmware.vmware
roles:
  - geerlingguy.docker

Python Libraries

In some cases, you’ll also have python library dependencies. These can be imported using the ansible pip module. Put the requirements.txt file into your repository. Since the pip module calls out the path, it can be anywhere however putting it where the requirements.yaml file is located, makes it easier to find and manage.

The file itself is just a list of modules you need in order for your playbooks to run. There are several available options, see the documentation to explore the capabilities.

Example requirements.txt file located in the project root.

certifi

When you want to load the modules, use the ansible pip module. In AWX, the project is located in /runner/project. It’s best to use the tilde though as other automation containers might have a different home directory.

---
- name: Install dependencies
  pip:
    requirements: "~/project/requirements.txt"

When this runs, it is located in the /runner/.local/lib/python3.9/site-packages directory.

Final

I write these articles in large part because I can’t find all the information I personally am looking for in one place. This is my view, my project, and of course my documentation. 🙂

References

• Galaxy Documentation – This doc does describe the options available in a requirements.yaml file.
• Article on the requirements.yaml file – This article discusses the requirements.txt file but isn’t as complete there as with the requirements.yaml file description.
• Documentation on the requirements.txt file