Ansible Builder & Execution Environments: Complete Guide (2026)

By Luca Berton · Published 2024-01-01 · Category: installation

Complete guide to Ansible Execution Environments. Build custom EEs with ansible-builder, configure execution-environment.yml, and manage container images.

What Are Execution Environments?

Execution Environments (EEs) are container images that package everything needed to run Ansible automation: ansible-core, Python dependencies, system packages, and collections. They ensure consistent, reproducible automation across development, CI/CD, and production.

Why Use Execution Environments?

Traditional Ansible installations suffer from dependency conflicts — different projects need different Python packages, collections, or system libraries. EEs solve this by isolating each automation project in its own container.

Benefits:

Reproducibility — same environment everywhere (laptop, CI/CD, AWX/AAP)
Isolation — no dependency conflicts between projects
Portability — share a single container image with your team
Consistency — development matches production exactly

Install ansible-builder

pip install ansible-builder

# Or install all dev tools
pip install ansible-dev-tools

# Verify
ansible-builder --version

execution-environment.yml (v3)

The execution-environment.yml file defines what goes into your EE:

---
version: 3

images:
  base_image:
    name: quay.io/ansible/ansible-runner:latest

dependencies:
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt

additional_build_files:
  - src: files/ansible.cfg
    dest: configs

additional_build_steps:
  prepend_galaxy:
    - ADD _build/configs/ansible.cfg /etc/ansible/ansible.cfg
  append_final:
    - RUN echo "Custom EE ready"

options:
  package_manager_path: /usr/bin/dnf

Dependency Files

requirements.yml (Collections)

---
collections:
  - name: amazon.aws
    version: ">=9.0.0"
  - name: community.docker
  - name: community.general
  - name: ansible.posix
  - name: community.vmware

requirements.txt (Python)

boto3>=1.35.0
botocore>=1.35.0
requests>=2.32.0
pyVmomi>=8.0
docker>=7.0
jmespath>=1.0

bindep.txt (System Packages)

gcc [compile]
python3-devel [compile]
libssh-devel [platform:centos-9 platform:rhel-9]
krb5-devel [kerberos]

Build Your EE

# Basic build
ansible-builder build --tag my-custom-ee:1.0

# With Podman (default)
ansible-builder build --tag my-ee:latest --container-runtime podman

# With Docker
ansible-builder build --tag my-ee:latest --container-runtime docker

# Verbose output
ansible-builder build --tag my-ee:latest -v 3

# Just generate the Containerfile (don't build)
ansible-builder create --file execution-environment.yml

Use Your EE

With ansible-navigator

# Interactive mode
ansible-navigator run playbook.yml --eei my-custom-ee:latest

# Stdout mode (like ansible-playbook)
ansible-navigator run playbook.yml --eei my-custom-ee:latest --mode stdout

# Pull policy
ansible-navigator run playbook.yml --eei my-custom-ee:latest --pp never

With ansible-navigator Settings

# ansible-navigator.yml
ansible-navigator:
  execution-environment:
    container-engine: podman
    image: my-custom-ee:latest
    pull:
      policy: missing
    volume-mounts:
      - src: /home/user/.ssh
        dest: /home/runner/.ssh
        options: ro
    environment-variables:
      set:
        AWS_PROFILE: production

With AWX / AAP

Push your EE to a container registry:

podman push my-custom-ee:latest quay.io/myorg/my-custom-ee:latest

In AWX/AAP, go to Administration → Execution Environments
Add your image URL: quay.io/myorg/my-custom-ee:latest
Assign to job templates

Base Images

Image	Description
`quay.io/ansible/ansible-runner:latest`	Standard base with ansible-core
`quay.io/ansible/awx-ee:latest`	AWX default EE
`registry.redhat.io/ansible-automation-platform-25/ee-minimal-rhel9`	AAP minimal
`registry.redhat.io/ansible-automation-platform-25/ee-supported-rhel9`	AAP supported

Complete Example: AWS + VMware EE

# execution-environment.yml
---
version: 3

images:
  base_image:
    name: quay.io/ansible/ansible-runner:latest

dependencies:
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt

additional_build_steps:
  append_final:
    - RUN pip install --upgrade pip

# requirements.yml
---
collections:
  - amazon.aws
  - community.vmware
  - community.general
  - ansible.posix
  - ansible.utils

# requirements.txt
boto3>=1.35.0
botocore>=1.35.0
pyVmomi>=8.0
jmespath>=1.0

# Build and test
ansible-builder build --tag aws-vmware-ee:1.0 -v 3
ansible-navigator run test-playbook.yml --eei aws-vmware-ee:1.0 --mode stdout

Troubleshooting

Build fails on dependencies

# Check the generated Containerfile
ansible-builder create
cat context/Containerfile

# Build with verbose
ansible-builder build --tag test:latest -v 3

Collection not found in EE

# Verify collections inside the EE
podman run --rm my-ee:latest ansible-galaxy collection list

Python package conflicts

# Check installed packages
podman run --rm my-ee:latest pip list

Offline/air-gapped builds

# Pre-download collections
ansible-galaxy collection download -r requirements.yml -p ./collections/

# Pre-download Python packages
pip download -r requirements.txt -d ./python-packages/

# Use local files in EE definition

Local Documentation (Offline Reference)

The ansible-builder package doesn't ship man pages. For offline reference:

# Find installed package location
python3 -c "import ansible_builder; print(ansible_builder.__file__)"

# Check for schema files
pip show ansible-builder | grep Location

# Generate a Containerfile to see interpreted fields
ansible-builder create --file execution-environment.yml

FAQ

What's the difference between EE v1, v2, and v3?

Version 3 (current) supports images section, additional_build_files, and improved dependency resolution. Always use v3 for new projects.

Do I need Podman or Docker?

Either works. Podman is the default and recommended (rootless containers). Docker works with --container-runtime docker.

Can I use EEs without ansible-navigator?

Yes — you can run containers directly: podman run --rm -v $(pwd):/runner my-ee:latest ansible-playbook playbook.yml

How do I update an EE?

Update your dependency files, bump the tag version, and rebuild: ansible-builder build --tag my-ee:2.0

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton