Introduction

If you’re just getting started with Red Hat Ansible Automation Platform (AAP), you may have heard the term “Execution Environment” thrown around and wondered what it means. By the end of this post, you’ll know exactly what they are, why they matter, and how to build one yourself using ansible-builder and Podman.

What Are Execution Environments?

In the early days of Ansible, you’d run playbooks directly from your local machine or a control node. That meant installing Python, Ansible, and all the necessary collections and dependencies directly on that system. This worked fine for small setups, but it quickly became a headache:

• Different projects needed different versions of Python libraries
• Dependency conflicts were common
• Reproducing the same environment across teams was painful

Execution Environments (EEs) solve this problem. An EE is a container image, built on top of a standard base image, that bundles together everything Ansible needs to run your playbooks:

• The Ansible engine itself
• Python and its dependencies
• Ansible Collections
• Any custom system packages your playbooks rely on

Think of it like a self-contained lunchbox: everything your automation needs is packed inside, sealed up, and ready to go, no matter where it runs. Whether that’s on your laptop, a CI/CD pipeline, or Ansible Automation Platform, the environment is always identical.

So, why does this matter to AAP?  Ansible Automation Platform runs all jobs inside Execution Environments by default. So understanding how to build and customize them is a foundational skill for working with AAP effectively.

Step-by-Step: Building Your First Execution Environment

We’ll use two tools:

• ansible-builder — a CLI tool from Red Hat that simplifies the process of building EE container images
• Podman — a daemonless, rootless container engine (the preferred runtime for AAP and EE builds)

Prerequisites

Before starting, make sure you have the following installed:

• Python 3.9+
• pip (Python package manager)
• Podman

You can verify Podman is installed by running:

podman --version

Step 1: Install ansible-builder

Install ansible-builder via pip:

pip install ansible-builder

Confirm the installation:

ansible-builder --version

Step 2: Create Your Project Directory

Create a folder for your EE project and navigate into it:

mkdir nutanix-ee && cd nutanix-ee

Step 3: Write the Execution Environment Definition File

The heart of every EE build is a file called execution-environment.yml. This file tells ansible-builder what to include in your image.

Create the file:

touch execution-environment.yml

Then open it and add the following (in this example, for a Nutanix configuration):

---
version: 3

images:
  base_image:
    name: <Container Registry URL>/ee-minimal-rhel9:latest

dependencies:
  galaxy:
    collections:
      - name: nutanix.ncp
  python:
    - ntnx-clustermgmt-py-client
    - ntnx-iam-py-client
    - ntnx-microseg-py-client
    - ntnx-volumes-py-client
    - ntnx-dataprotection-py-client
    - ntnx-datapolicies-py-client
    - ntnx-lifecycle-py-client
    - ntnx-objects-py-client
    - ntnx-security-py-client
    - ntnx-licensing-py-client
    - ntnx-vmm-py-client
    - ntnx-prism-py-client
    - ntnx-networking-py-client
    - ntnx-storage-py-client
    - ntnx-clustermgmt-py-client
  system:
    - libxcrypt-compat # Required for RHEL/CentOS 9+ based images

options:
  package_manager_path: /usr/bin/microdnf

Let’s break this down:

Note: If you don’t have access to registry.redhat.io, you can substitute the base image with a community alternative like ghcr.io/ansible/community-ee-base:latest for testing purposes.

Note:  Included in the example is a section labeled package_manager_path.  This was needed by Red Hat images because to slim down the container size, they used microdnf instead of dnf.  This ensures that the image used will use the right package manager and won’t throw errors when creating!

Step 4: Build the Execution Environment

Now run the build:

ansible-builder build -t nutanix-ee:1.0 -v 3

Here’s what the flags mean:

• -t nutanix-ee:1.0 — tags your image with a name and version
• -v 3 — sets verbosity level so you can see what’s happening

Under the hood, ansible-builder generates a Containerfile and uses Podman to build the final image. You’ll see output as it pulls the base image, installs collections, and installs Python dependencies.

Step 5: Verify the Image

Once the build completes, confirm your image exists:

podman images

You should see nutanix-ee listed with the 1.0 tag.

You can also do a quick sanity check by running Ansible inside your new EE:

podman run --rm nutanix-ee:1.0 ansible --version

If Ansible prints its version info, your Execution Environment is working correctly!

Step 6: Push the Image to a Registry

To use your EE with Ansible Automation Platform, you’ll need to publish it to a container registry (such as Quay.io, Docker Hub, or a private registry):

podman tag nutanix-ee:1.0 quay.io/<your-username>/nutanix-ee:1.0
podman push quay.io/<your-username>/nutanix-ee:1.0

You can then reference this image in AAP when configuring a Job Template.

What’s Next?

Now that you’ve built your first Execution Environment, here are some natural next steps to explore:

• Using a private Automation Hub — pull collections from your organization’s internal Automation Hub instead of the public Galaxy
• Versioning your EEs — treat your execution-environment.yml like code: commit it to Git and build new versions as your dependencies evolve

Wrapping Up

Execution Environments are one of the most important concepts in modern Ansible Automation Platform. They bring consistency, portability, and reliability to your automation and with ansible-builder and Podman, building them is more approachable than it might first seem.

Start simple, get comfortable with the workflow, and gradually customize your EEs as your automation needs grow.