Execution Environment Guide

Ansible Execution Environments (EEs) are container images that bundle ansible-core, collections, and their Python and system dependencies. They are the standard runtime for Red Hat Ansible Automation Platform and AWX, replacing the older virtualenv model. They can also be used outside of RHAAP and AWX by using ansible-navigator, or by using ansible-runner directly.

What runs in the EE

Only controller-side plugins run inside the EE. Their Python and system dependencies must be installed there. This includes: lookup plugins, inventory plugins, callback plugins, connection plugins, become plugins, and filter plugins.

Modules run on the managed nodes and are transferred there at runtime — their dependencies must be present on the target, not in the EE.

Note

Modules delegated to localhost (for example, those that interact with a remote API) are an exception: they run on the controller and their dependencies must therefore be available in the EE.

Why community.general does not provide EE metadata

community.general ships dozens of controller-side plugins covering a very broad range of technologies. Bundling the dependencies for all of them into a single EE image would almost certainly create irreconcilable conflicts — both within the collection and with other collections or tools (such as ansible-lint) that share the same image.

For that reason, community.general does not provide Python or system package dependency metadata. Users are expected to build purpose-built, minimal EEs containing only the dependencies required by the specific plugins they actually use.

Finding the dependencies you need

Every plugin that has external dependencies documents them in its requirements field. You can inspect those with ansible-doc:

$ ansible-doc -t lookup community.general.some_lookup | grep -A 10 "REQUIREMENTS"

Or browse the plugin’s documentation page on docs.ansible.com.

For example, a lookup plugin that wraps an external service might list:

requirements:
  - some-python-library >= 1.2

An inventory plugin backed by a REST API might list:

requirements:
  - requests
  - some-sdk

These are the packages you need to add to your EE.

Building a minimal EE with ansible-builder

ansible-builder is the standard tool for creating EEs.

Install it with:

$ pip install ansible-builder

Create an execution-environment.yml in your own project — not inside community.general — that includes only the dependencies needed for the plugins you use:

version: 3

dependencies:
  galaxy:
    collections:
      - name: community.general
  python:
    - some-python-library>=1.2
    - requests
  system:
    - libxml2-devel [platform:rpm]

images:
  base_image:
    name: ghcr.io/ansible/community-ee-base:latest

Then build the image:

$ ansible-builder build -t my-custom-ee:latest

See also