Build, Publish, and Consume a Custom Execution Environment for Red Hat Ansible Automation Platform

Desired Outcome

Deliver a reproducible, version‑controlled Execution Environment (EE) image that contains the exact Python packages and Ansible collections needed for your team’s playbooks, publish it to Automation Hub, and configure an Automation Controller job template to use the new EE.

Prerequisites

• Red Hat Automation Hub subscription with push rights.
• Container registry (Quay.io, Docker Hub, or internal registry) with write access. Example: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel8 as the base image.
• Linux workstation with podman (or Docker) and ansible-builder installed. ansible-builder requires Python 3.8+.
• Git repository containing execution-environment.yml and requirements.txt.
• Credentials for the container registry and Automation Hub (stored in ~/.docker/config.json and ~/.ansible-hub.cfg).

Step‑by‑Step Procedure

1. Define the EE

Create a directory for the EE definition and add the following files.

mkdir myee && cd myee
cat > execution-environment.yml <<'EOF'
name: myorg/my-ee
version: 1.0.0
dependencies:
  python: requirements.txt
  ansible-core: 2.14.0
  collections:
    - community.general
    - myorg.custom
EOF

cat > requirements.txt <<'EOF'
# Python packages
requests==2.28.1
# Add any additional modules here
EOF

Explanation: execution-environment.yml tells ansible-builder which base image to use, which Python packages to install, and which Ansible collections to bundle. The requirements.txt file lists pip packages. Adjust versions to match your policy.

2. Build the EE Image

# Build locally and tag the image for the registry
ansible-builder build -t myorg/my-ee:1.0.0

Run the command as a user with podman permissions. The build logs will show layers being pulled and packages installed. If the build fails, check the ansible-builder output for missing dependencies or network issues.

3. Test the Image Locally

# Verify the EE contains the expected Ansible version
podman run --rm myorg/my-ee:1.0.0 ansible --version

# List installed collections
podman run --rm myorg/my-ee:1.0.0 ansible-galaxy collection list

Confirm the output matches the versions specified in the definition. No missing modules should appear.

4. Push to Automation Hub

There are two common ways to publish the EE:

• UI: Log into the Automation Hub web interface, navigate to "Execution Environments", click "Add", and supply the image name myorg/my-ee:1.0.0. The UI will pull the image from the registry and store metadata.
• CLI (recommended for repeatability):

  # Authenticate with Hub
  ansible-hub login --username <hub_user> --password <hub_pass>
  
  # Push the EE
  ansible-hub ee push myorg/my-ee:1.0.0
  

Ensure the registry credentials are present in ~/.docker/config.json so the CLI can pull the image before pushing metadata.

5. Attach EE to a Job Template

# In Automation Controller UI
1. Open the desired job template.
2. Edit the "Execution Environment" field.
3. Select "Use a custom execution environment".
4. Enter the EE name: myorg/my-ee:1.0.0.
5. Save and launch a test job.

Alternatively, use the awx CLI:

awx job_template update --name "My Template" --execution-environment "myorg/my-ee:1.0.0"

Expected Checks

• Job output shows ansible‑core 2.14.0 and the collections listed in the EE definition.
• No "No module named" or "Missing dependency" errors in the job logs.
• Container logs (if enabled) indicate the base image was pulled without errors.
• In Automation Hub, the EE record lists the correct image tag and metadata.

Recovery Options

• Build failure: Inspect the ansible-builder output. Common fixes include adding missing pip packages to requirements.txt or updating the base image name.
• Push failure: Verify registry credentials, network connectivity, and that the image tag matches the one you built. Re‑run the push command after correcting any issues.
• Job failure due to missing dependencies: Re‑build the EE with the missing package, push again, and update the job template to point to the new tag.
• Downtime when changing EE for live jobs: Prefer creating a new job template with the updated EE instead of editing an existing one, or schedule the change during a maintenance window.

Limitations & Practical Verification

• Using a minimal base image (ee‑minimal‑rhel8) keeps the EE lean, but you must explicitly list every collection you need.
• Large EE images increase job start‑up time; monitor the controller’s job queue to detect any performance regressions.
• Security updates to the base image are applied automatically only if you rebuild the EE. Implement a CI pipeline that rebuilds and pushes the EE on a regular cadence.
• To verify the EE is truly isolated, run a playbook that imports a custom module and ensure it executes without referencing host‑system libraries.

By following this guide, you ensure that every team member runs playbooks against the same, auditable set of dependencies, reducing “works on my machine” issues and simplifying compliance audits.