Execution Environments

Last updated: January 12, 2026

📚 Reference: This guide aligns with the official Getting started with Execution Environments documentation.

My Journey to Execution Environments

After years of managing Ansible across different teams and environments, I've encountered a recurring challenge: dependency hell. One team needs Python 3.8 with specific libraries, another needs Python 3.11, and a third team requires completely different collections and modules. Managing these dependencies on a shared control node was becoming a nightmare. That's when I discovered Execution Environments (EEs) – and it transformed how I approach Ansible automation.

What Are Execution Environments?

Execution Environments are container images that serve as Ansible control nodes. Think of them as self-contained, portable automation units that include:

• Ansible Core or Ansible

• Ansible Collections and their dependencies

• Python packages required by modules

• System packages needed for specific tasks

• Custom plugins and modules

Instead of installing dependencies directly on your control node, you package everything into a container image that can be shared, versioned, and run consistently anywhere.

Why Use Execution Environments?

From my experience, here are the compelling reasons to adopt EEs:

1. Dependency Isolation

Different automation projects can have completely different requirements without conflict. One EE can use Ansible 2.15 with specific collections, while another uses Ansible 2.17 with different dependencies.

2. Consistency Across Environments

The same container that works on your laptop will work in CI/CD pipelines, on your colleague's machine, and in production automation platforms. No more "works on my machine" issues.

3. Version Control for Dependencies

Your entire automation stack – Ansible version, collections, Python libraries – is versioned as a container image. You can roll back to previous versions if needed.

4. Simplified Onboarding

New team members just pull the EE container image and start running playbooks. No lengthy setup process or dependency installation.

5. Security and Compliance

Scan container images for vulnerabilities, ensure only approved dependencies are used, and maintain a clear audit trail of what's running where.

6. Cloud-Native Integration

EEs work seamlessly with Kubernetes, OpenShift, and other container orchestration platforms.

Understanding the Architecture

Here's how Execution Environments fit into the Ansible ecosystem:

Getting Started with Execution Environments

Prerequisites

Install the required tools:

# Install ansible-builder (creates EE images)
pip install ansible-builder

# Install ansible-navigator (runs playbooks in EEs)
pip install ansible-navigator

# Ensure you have a container runtime
# Podman (recommended) or Docker
# For macOS:
brew install podman

# For Linux:
sudo dnf install podman  # or apt install podman

Creating Your First Execution Environment

Step 1: Define Your Requirements

Create an execution-environment.yml file:

---
version: 3

# Base image to start from
images:
  base_image:
    name: quay.io/ansible/creator-ee:latest

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

# Additional build steps (optional)
additional_build_steps:
  prepend_galaxy:
    - RUN echo "Installing collections..."
  append_final:
    - RUN echo "Build complete!"

Step 2: Define Collection Requirements

Create requirements.yml:

---
collections:
  # Core collections you need
  - name: ansible.posix
    version: ">=1.5.0"
  
  - name: community.general
    version: ">=8.0.0"
  
  - name: amazon.aws
    version: ">=7.0.0"
  
  # Your organization's custom collections
  - name: myorg.infrastructure
    source: https://github.com/myorg/ansible-collections

Step 3: Define Python Dependencies

Create requirements.txt:

# AWS modules dependencies
boto3>=1.28.0
botocore>=1.31.0

# Azure modules dependencies
azure-mgmt-compute>=30.0.0
azure-mgmt-network>=25.0.0

# Other utilities
jmespath>=1.0.0
netaddr>=0.8.0
requests>=2.31.0

Step 4: Define System Dependencies

Create bindep.txt:

# System packages needed by your automation
git [platform:rpm]
git [platform:dpkg]
rsync [platform:rpm]
rsync [platform:dpkg]
openssh-clients [platform:rpm]
openssh-client [platform:dpkg]

Step 5: Build Your Execution Environment

# Build the EE image
ansible-builder build --tag myorg/ansible-ee:1.0.0

# This will:
# 1. Generate a Containerfile
# 2. Build the container image
# 3. Tag it with the specified name

Step 6: Test Your Execution Environment

# Run a simple playbook using the EE
ansible-navigator run playbook.yml \
  --execution-environment-image myorg/ansible-ee:1.0.0 \
  --mode stdout

# Or in interactive mode (recommended for development)
ansible-navigator run playbook.yml \
  --execution-environment-image myorg/ansible-ee:1.0.0

Real-World Example: Multi-Cloud Automation EE

Here's a practical example for an organization managing AWS, Azure, and on-premise infrastructure:

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:
  prepend_base:
    - RUN dnf install -y python3.11
  prepend_galaxy:
    - COPY custom_modules/ /usr/share/ansible/plugins/modules/
  append_final:
    - RUN ansible-galaxy collection list

requirements.yml

---
collections:
  # AWS automation
  - name: amazon.aws
    version: ">=7.1.0"
  
  # Azure automation
  - name: azure.azcollection
    version: ">=2.0.0"
  
  # VMware automation
  - name: community.vmware
    version: ">=4.0.0"
  
  # Network automation
  - name: cisco.ios
    version: ">=5.0.0"
  
  # Kubernetes/OpenShift
  - name: kubernetes.core
    version: ">=3.0.0"
  
  # Security and compliance
  - name: ansible.posix
    version: ">=1.5.0"
  
  # General utilities
  - name: community.general
    version: ">=8.0.0"

requirements.txt

# AWS SDK
boto3>=1.29.0
botocore>=1.32.0

# Azure SDK
azure-mgmt-compute>=30.3.0
azure-mgmt-network>=25.1.0
azure-mgmt-resource>=23.0.0
azure-identity>=1.15.0

# VMware
pyvmomi>=8.0.0

# Kubernetes
kubernetes>=28.0.0
openshift>=0.13.0

# Network automation
paramiko>=3.4.0
netmiko>=4.3.0

# Utilities
jmespath>=1.0.1
jinja2>=3.1.0
pyyaml>=6.0.1
requests>=2.31.0

Using ansible-navigator

ansible-navigator is the modern CLI for running playbooks with EEs. Here's how I use it:

Basic Playbook Execution

# Run in interactive mode (great for debugging)
ansible-navigator run site.yml \
  --execution-environment-image myorg/ansible-ee:1.0.0 \
  --inventory inventory/production.yml

# Run in stdout mode (for CI/CD)
ansible-navigator run site.yml \
  --execution-environment-image myorg/ansible-ee:1.0.0 \
  --inventory inventory/production.yml \
  --mode stdout

Configuration File

Create ansible-navigator.yml to avoid repeating parameters:

---
ansible-navigator:
  execution-environment:
    image: myorg/ansible-ee:1.0.0
    pull:
      policy: missing  # Only pull if not present locally
    container-engine: podman
    
  playbook-artifact:
    enable: true
    save-as: /tmp/playbook-artifacts/{playbook_name}-{time_stamp}.json
    
  logging:
    level: info
    file: /tmp/ansible-navigator.log
    
  mode: interactive  # or stdout
  
  inventory:
    - inventory/production.yml

Now you can simply run:

ansible-navigator run site.yml

Managing Execution Environment Images

Best Practices for EE Management

1. Version Your Images

# Build with semantic versioning
ansible-builder build --tag myorg/ansible-ee:2.1.0

# Also tag as latest for convenience
podman tag myorg/ansible-ee:2.1.0 myorg/ansible-ee:latest

2. Use a Container Registry

# Push to your registry
podman login registry.myorg.com
podman push myorg/ansible-ee:2.1.0 registry.myorg.com/automation/ansible-ee:2.1.0

# Pull on other systems
podman pull registry.myorg.com/automation/ansible-ee:2.1.0

3. Scan for Vulnerabilities

# Using trivy
trivy image myorg/ansible-ee:2.1.0

# Using podman/buildah
podman scan myorg/ansible-ee:2.1.0

4. Keep Images Lean

# In execution-environment.yml
additional_build_steps:
  append_final:
    - RUN dnf clean all
    - RUN rm -rf /var/cache/dnf

Advanced Patterns

Multi-Stage Builds

For complex EEs, use multi-stage builds to keep the final image small:

---
version: 3

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

additional_build_steps:
  prepend_base:
    # Install build dependencies
    - RUN dnf install -y gcc python3-devel
  
  append_final:
    # Remove build dependencies to reduce image size
    - RUN dnf remove -y gcc python3-devel
    - RUN dnf clean all

Custom Base Images

Create a custom base image for your organization:

# custom-base/Containerfile
FROM registry.access.redhat.com/ubi9/ubi:latest

# Install your standard tools
RUN dnf install -y \
    python3.11 \
    python3.11-pip \
    git \
    openssh-clients \
    && dnf clean all

# Set up Python virtual environment
RUN python3.11 -m venv /opt/ansible-venv
ENV PATH="/opt/ansible-venv/bin:$PATH"

# Install Ansible
RUN pip install --upgrade pip && \
    pip install ansible-core==2.16.0

Then use it in your EE:

---
version: 3

images:
  base_image:
    name: myorg/ansible-base:latest

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

Environment-Specific EEs

Build different EEs for different purposes:

# Development EE with debugging tools
ansible-builder build \
  --file execution-environment-dev.yml \
  --tag myorg/ansible-ee:dev

# Production EE - minimal and hardened
ansible-builder build \
  --file execution-environment-prod.yml \
  --tag myorg/ansible-ee:prod

# Testing EE with test frameworks
ansible-builder build \
  --file execution-environment-test.yml \
  --tag myorg/ansible-ee:test

Integration with CI/CD

GitLab CI Example

# .gitlab-ci.yml
stages:
  - build
  - test
  - deploy

build-ee:
  stage: build
  image: quay.io/ansible/ansible-builder:latest
  script:
    - ansible-builder build --tag $CI_REGISTRY_IMAGE/ansible-ee:$CI_COMMIT_SHA
    - podman push $CI_REGISTRY_IMAGE/ansible-ee:$CI_COMMIT_SHA

test-playbooks:
  stage: test
  image: quay.io/ansible/ansible-navigator:latest
  script:
    - ansible-navigator run tests/test-playbook.yml
        --execution-environment-image $CI_REGISTRY_IMAGE/ansible-ee:$CI_COMMIT_SHA
        --mode stdout

deploy-infrastructure:
  stage: deploy
  image: quay.io/ansible/ansible-navigator:latest
  script:
    - ansible-navigator run site.yml
        --execution-environment-image $CI_REGISTRY_IMAGE/ansible-ee:$CI_COMMIT_SHA
        --mode stdout
        --inventory inventory/production.yml
  only:
    - main

GitHub Actions Example

# .github/workflows/ansible-automation.yml
name: Ansible Automation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Install ansible-builder
      run: pip install ansible-builder ansible-navigator
    
    - name: Build Execution Environment
      run: |
        ansible-builder build \
          --tag ghcr.io/${{ github.repository }}/ansible-ee:${{ github.sha }}
    
    - name: Run tests
      run: |
        ansible-navigator run tests/test-playbook.yml \
          --execution-environment-image ghcr.io/${{ github.repository }}/ansible-ee:${{ github.sha }} \
          --mode stdout
    
    - name: Push to GitHub Container Registry
      if: github.ref == 'refs/heads/main'
      run: |
        echo ${{ secrets.GITHUB_TOKEN }} | podman login ghcr.io -u ${{ github.actor }} --password-stdin
        podman push ghcr.io/${{ github.repository }}/ansible-ee:${{ github.sha }}

Troubleshooting Common Issues

Issue 1: Image Build Fails

# Enable verbose output
ansible-builder build --tag myorg/ansible-ee:1.0.0 --verbosity 3

# Check the generated Containerfile
cat context/Containerfile

Issue 2: Collections Not Found

# Verify collections in the EE
podman run --rm myorg/ansible-ee:1.0.0 ansible-galaxy collection list

# Check specific collection
podman run --rm myorg/ansible-ee:1.0.0 ansible-galaxy collection list | grep amazon.aws

Issue 3: Python Dependencies Missing

# Check installed Python packages
podman run --rm myorg/ansible-ee:1.0.0 pip list

# Test specific import
podman run --rm myorg/ansible-ee:1.0.0 python3 -c "import boto3; print(boto3.__version__)"

Issue 4: SSH Key Access

When using SSH keys with EEs:

# Mount SSH keys into the container
ansible-navigator run site.yml \
  --execution-environment-image myorg/ansible-ee:1.0.0 \
  --execution-environment-volume-mounts $HOME/.ssh:/home/runner/.ssh:Z

Or configure in ansible-navigator.yml:

ansible-navigator:
  execution-environment:
    volume-mounts:
      - src: /home/user/.ssh
        dest: /home/runner/.ssh
        options: Z

Migration from Traditional Ansible

Gradual Migration Strategy

1. Start with a Base EE: Use an official EE as-is

2. Add Collections Incrementally: Add your collections one at a time

3. Test Thoroughly: Verify all playbooks work in the EE

4. Document Dependencies: Record what each playbook needs

5. Optimize: Remove unused dependencies

Migration Checklist

• Inventory current Ansible version and collections

• Document Python dependencies

• Identify system packages needed

• Create initial execution-environment.yml

• Build and test first EE

• Run existing playbooks in EE

• Address any failures

• Document the new workflow

• Train team members

• Update CI/CD pipelines

Best Practices Summary

From my experience deploying EEs across multiple organizations:

1. Keep Images Small: Only include what you need

2. Version Everything: Tag images with semantic versions

3. Use Private Registries: For organizational EEs

4. Scan for Vulnerabilities: Make it part of your build process

5. Document Requirements: Clear execution-environment.yml files

6. Test Before Pushing: Verify EEs work before sharing

7. Pin Versions: Use specific versions in production

8. Automate Builds: Build EEs in CI/CD pipelines

9. Monitor Image Sizes: Keep track of bloat

10. Regular Updates: Keep base images and dependencies current

Conclusion

Execution Environments represent a significant evolution in how we run Ansible automation. They solve real problems around dependency management, consistency, and portability. While there's a learning curve, the benefits – especially in team environments and CI/CD pipelines – make EEs essential for modern Ansible usage.

Whether you're managing a small team or enterprise-scale automation, EEs will help you deliver more reliable, consistent automation with less friction.

---

Further Reading

• Official Execution Environments Guide

• ansible-builder Documentation

• ansible-navigator Documentation

• Red Hat Ansible Automation Platform EE Docs

Ready to containerize your automation? Start building your first Execution Environment today! 🐳