Building a Custom Execution Environment for Ascender

Introduction

Ascender uses Execution Environments to run Ansible playbooks inside containerized environments. The default EE that ships with Ascender includes a standard set of Ansible collections, Python packages, and system binaries. However, some Ansible modules require additional Python libraries or system packages that aren't included in the default image.

This article covers how to build a custom Execution Environment that includes additional Python packages, system dependencies, or Ansible collections, and how to configure Ascender to use it.

Problem

Certain Ansible modules require Python libraries that aren't included in Ascender's default Execution Environment. For example, the netbox.netbox collection modules require the pynetbox Python package. When running a playbook that uses one of these modules with delegate_to: localhost or as part of a dynamic inventory plugin, the task fails because the required Python library is not present in the EE container.

Unlike Ansible collections, which Ascender installs automatically during project sync via a collections/requirements.yml file, Python packages can't be installed at runtime. There isn't a pip install mechanism during job execution. The only way to include additional Python packages is to build a custom Execution Environment image that contains them.

Symptoms

When a required Python package is missing from the Execution Environment, Ansible tasks fail with errors similar to:

fatal: [localhost]: FAILED! => {"changed": false, "msg": "Failed to import the required Python library (pynetbox) on localhost. Please read the module documentation and install it in the appropriate location."}

Resolution

Prerequisites

The following are required on your build host:

• ansible-builder (installed via pip)
• A container runtime: podman or docker
• Access to a container registry, such as GitHub Container Registry, Quay.io, or a private registry

Step 1: Clone the Ascender EE repository

CIQ publishes the source for the default Ascender Execution Environment. Fork or clone this repository as your starting point:

git clone https://github.com/ctrliq/ascender-ee
cd ascender-ee

Step 2: Modify the EE definition

Edit execution-environment.yml to add your required dependencies.

To add Python packages, add entries to the python: block:

python: |
  pynetbox
  ansible-sign
  jmespath

To add system packages, add entries to the system: block in the same file.

To add Ansible collections, add entries to the galaxy: block.

Step 3: Install ansible-builder

If you don't already have ansible-builder installed on your build host:

pip3 install ansible-builder

Step 4: Build the custom EE image

Build the image, tagging it for your target registry:

ansible-builder build -t your-registry.example.com/custom-ascender-ee:v1 -v3

The first build pulls in all collections and system packages, so it takes some time. Subsequent builds are faster due to layer caching.

Step 5: Push the image to your registry

podman push your-registry.example.com/custom-ascender-ee:v1

If you are using the ctrliq/ascender-ee GitHub repository directly (or a fork of it), the included GitHub Actions workflow can build and push the image to GitHub Container Registry automatically on push.

Step 6: Add the EE to Ascender

1. In the Ascender UI, navigate to Administration > Execution Environments > Add
2. Give the Execution Environment a name, for example "Custom EE with pynetbox"
3. Set the Image field to the full registry path, such as your-registry.example.com/custom-ascender-ee:v1
4. Select a Pull policy appropriate for your environment
5. If the registry requires authentication, select the appropriate Credential
6. Click Save

Step 7: Assign the EE to your Job Template

Edit the Job Template that needs the custom Python packages and set the Execution Environment field to the new EE you created. Any jobs launched from this template now use the custom image, and the additional Python packages are available.

References & related articles

Ascender Execution Environments documentation
Ansible community Getting Started with Execution Environments
CIQ Ascender EE source repository