Custom AWX Execution Environment

Posted on

From what I can tell a Execution Environment in the AWX context is a container which gets created into a kubernetes pod whenever a playbook executes.

AWX can use several of these environment containers, so depending on needs custom containers can be created that contain different Python packages, Ansible collections and so on.

I wanted to create a custom container so ensure a newer version of Ansible was available, ansible-pylibssh was installed and the collections I used was already installed when a playbook was started.

To do this some files are required, and the ansible-builder tool will be used to create the container.

The files

execution-environment.yml

This file defines the environment:

---
version: 3
images:
  base_image:
    name: quay.io/centos/centos:stream10
dependencies:
  ansible_core:
    package_pip: ansible-core
  ansible_runner:
    package_pip: ansible-runner
  galaxy: requirements.yml
  system: bindep.txt
  python: requirements.txt
additional_build_steps:
  append_base:
    - RUN $PYCMD -m pip install -U pip
  append_final:
    - RUN git lfs install --system

This will install the latest available version of ansible-core and ansible-runner, look for other requirements in the files specified and execute some commands.

bindep.txt

Contains the software that should be installed in the environment, from the OS package manager.

git-core [platform:rpm]
git-lfs [platform:rpm]
epel-release [platform:rpm]

requirements.yml

A list of Ansible collections to be installed from Galaxy.

---
collections:
  - name: ansible.netcommon
  - name: ansible.posix
  - name: ansible.utils
  - name: awx.awx
  - name: cisco.iosxr
  - name: containers.podman
  - name: netbox.netbox

requirements.txt

Python modules to be install via pip.

ansible-pylibssh

Create the environment

Once the files are created ansible-builder can be used to create the container:

ansible-builder build -v3 -t custom-environment

Depending on the number of dependencies this will take a while but once it's done you should have a container which can be tagged and used. I push it to a local container registry:

docker tag custom-environment ee:latest
docker push ee:latest

Using the environment

If your container registry requires a credential you have to create a "Container Registry" credential.

To add the environment to AWX, log in as an admin user and to go Administration and Execution Environments. Click the add button and fill in the fields as necessary.

Then ensure you pick the correct execution environment in your job templates.