Skip to content

Ansible Execution Environment Documentation

Welcome to the documentation for the Ansible Execution Environment (EE) builder project.

Why this documentation: to give new and advanced users actionable, task-focused guides and the background needed to make sound design decisions with EEs.

What is an Execution Environment?

In modern automation, a common challenge is ensuring that your Ansible Playbooks run reliably everywhere. An automation might work on your laptop but fail in a CI/CD pipeline because of a different version of Python, a missing library, or an incompatible Ansible Collection.

An Execution Environment solves this problem. It is a self-contained container image that packages everything your automation needs to run:

  • A specific version of Ansible
  • Specific versions of Python packages
  • Required Ansible Collections
  • Any necessary system-level libraries or tools

By running your playbooks inside an EE, you guarantee a consistent, predictable, and portable environment for your automation, no matter where it runs.

Why Use This Project?

While you can build Execution Environments from scratch, this repository provides a framework to make the process standardized, repeatable, and easy to customize.

  • For New Users: It provides a "batteries-included" starting point. You can simply edit a few text files to define your dependencies, run make build, and get a working EE without needing to be an expert in containerization.
  • For Advanced Users: It offers a flexible and powerful way to manage the entire lifecycle of your EEs. The Makefile provides hooks to clean, build, test, inspect, and publish your images, and the configuration files offer deep customization options.

This documentation will guide you through understanding, using, and extending this framework.

⚡ Quick Reference for New Users

First Steps: 1. Clone the repository 2. Run make setup to verify your environment 3. Set ANSIBLE_HUB_TOKEN environment variable (for certified collections) 4. Run make build to create your execution environment 5. Run make test to verify it works

Key Insights: - ✅ make setup - Verify environment before building (catches issues early) - ✅ Python 3.10+ required - Python 3.11 recommended on RHEL 9 - ✅ python3-pip must be in bindep.txt - Minimal images don't include pip by default - ✅ Token only needed for build/token - test/setup/lint work without token - ✅ Use --pull-policy never - Ensures local images are used for testing - ✅ Minimal images are minimal - Use test -f instead of which command

Common Issues: - "No module named pip" → Add python3-pip [platform:rpm] to files/bindep.txt - Token errors on test → Token check now only runs when needed - Image pull errors → Test target uses --pull-policy never - Missing which command → Use test -f /path/to/binary instead

See Troubleshoot EE Builds for detailed solutions.

📚 Learning-Oriented: Tutorials

Start here to build your first custom Execution Environment. - Getting Started with Execution Environments Who this is for: new users; outcome: a working EE build.

🔧 Task-Oriented: How-To Guides

Practical guides for specific tasks and more advanced usage. - How to Test Your Execution Environment - How to Add Windows Support - Build Locally with Makefile and Podman - Enable Kubernetes and OpenShift Tooling - Troubleshoot EE Builds - Advanced Usage Guide - CI/CD with GitHub Actions and Tekton - Optional llms.txt Manifest - Build Docs Locally (MkDocs) Who this is for: practitioners executing tasks; outcome: one concrete result per guide.

📖 Information-Oriented: Reference

Detailed technical reference for the tools and configuration. - Optional Configs and Secrets - Make Targets and Variables - execution-environment.yml Reference - Tooling Reference Who this is for: readers needing exact options and commands.

💡 Understanding-Oriented: Explanation

Conceptual documentation to understand the underlying architecture and design. - Execution Environment Concepts - Technology Stack - Design Decisions - Why Keep execution-environment.yml Minimal Who this is for: decision-makers and maintainers; outcome: understand trade-offs and rationale.