Building Ansible Execution Environments with Non-Default Collections

Introduction

..............
An Ansible Execution Environment is a self-contained, portable environment that wraps everything needed to run Ansible automation tasks. This includes the Ansible core libraries, collections, python dependencies, and any other tools or packages needed to execute playbooks.

Ansible Execution environments are built using container technologies such as Docker or Podman and are defined using an ansible-builder configuration file.

This environment is used when using an ansible automation platform.

When you run Ansible from a computer, you have the option to use collections that are embedded into Ansible Core or to download collections from Ansible Galaxy. However, when you run Ansible from an automation platform, it is recommended to add the collections e.g. community.windows into the execution environment, as this would allow you to have a consistent environment, and a simplified setup.

This guide will show you how to build an execution environment, and include any collection or custom collection into the environment.

1. Create a Requirement File

The first task is to create a requirements.yml file that lists your desired collection. For instance, the community.windows collection. This file tells the Ansible automation platform (AWX or Ansible Tower) which collection/s (and optionally, Ansible roles) to include in the custom execution environment. Here's how your requirements.yml file might look:

---
collections:
  - name: community.windows

2. Build the Execution Environment

There are several ways to build the execution environment. One common method is to use the ansible-builder tool, which reads your requirements.yml file and generates a container image including all specified collections and roles.

Here's an example execution-environment.yml for ansible-builde:

version: 1
dependencies:
  galaxy: requirements.yml

Run ansible-builder build with this file and your requirements.yml file in the same directory to create a new execution environment image. For example:

ansible-builder build -t my_custom_environment:latest

This command builds a new container image named my_custom_environment with the community.windows collection installed.

3. Push the Image to a Container Registry

Once the image is built, you may need to push it to a container registry if your AWX or Tower instance runs in an environment where it cannot access local images directly. for best practice, push your image to a container registry

docker push my_custom_environment:latest

4. Import the Execution Environment into AWX/Tower

Next, you'll need to import your custom execution environment into AWX or Tower:

• Log into the AWX/Tower UI.
• Navigate to Administration > Execution Environments.
• Click on Add.
• Fill in the necessary information, including the image location from your container registry.
• Save your new execution environment.

5. Use the Custom Execution Environment

Finally, assign the new execution environment to your projects, job templates, or workflows as needed:

• Navigate to the job template or project configuration where you want to use the custom execution environment.
• Select your custom execution environment from the dropdown list.
• Save the configuration.

Your AWX or Tower jobs that use this template or project will now run using the custom execution environment, which includes the community.windows collection.

This process requires administrative access to AWX or Ansible Tower and potentially to the command line of a system where you can install and use ansible-builder. Ensure you have the necessary permissions and access before proceeding.