AnsibleByExample

Ansible Execution Environment Example: Adding a Collection via the EE Builder

Advanced
2024-01-014By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

The Execution Environment (EE) Builder in AAP 2.7's Automation Portal is a 4-step visual wizard for assembling custom EEs without hand-writing an execution-environment.yml. Step 2, Configuration, is where you attach collections to the base image you picked in Step 1. This example walks through adding redhat.rhel_system_roles v1.20.5 from Private Automation Hub.

Once the EE Builder publishes and builds your image, you reference it in a playbook like any other EE:

---
- name: Apply RHEL system roles using a custom-built execution environment
  hosts: rhel_servers
  become: true

  vars:
    ee_image: "registry.example.com/aap/ee-rhel-system-roles:latest"

  tasks:
    - name: Confirm rhel_system_roles collection is available in this EE
      ansible.builtin.debug:
        msg: "Running from execution environment {{ ee_image }}"

    - name: Configure timesync using redhat.rhel_system_roles
      ansible.builtin.import_role:
        name: redhat.rhel_system_roles.timesync
      vars:
        timesync_ntp_servers:
          - hostname: 0.pool.ntp.org
            iburst: true
          - hostname: 1.pool.ntp.org
            iburst: true

Walkthrough: Step 2 of the EE Builder

  1. Start from Step 1. Choose a Red Hat-provided base image — for new builds, pick the recommended Red Hat Ansible Minimal EE (Ansible Core 2.18 on RHEL 9). A stable-channel variant of 2.18, plain Ansible Core 2.16 on RHEL 9, its stable-channel variant, or a fully custom base image are also selectable if you have compatibility constraints.
  2. Move to Step 2: Configuration. The collections picker searches two sources: Private Automation Hub (rh-certified content) and GitHub. Type rhel_system_roles in the search box, select the redhat.rhel_system_roles result, and pin the version to 1.20.5.
  3. Add more collections if needed. Repeat the search/add action for every additional collection your playbooks require — each one is appended to the EE's dependency list shown on the same screen.
  4. Open Advanced Configuration (optional). This is where you add extra Python requirements (e.g., a package your custom modules import), extra RPM/system packages, and custom build steps (pre- or post-install shell commands) that the base execution-environment.yml schema alone can't express.
  5. Continue to Step 3: Destination and Build. Name the EE definition, add a description and tags, and choose whether to publish the definition to a Git repository (GitHub, authenticated) and trigger an automatic build immediately.
  6. Finish at Step 4: Review. The wizard validates the base image, collection list, and advanced settings before the build actually runs.

What this does and why

The picker resolves redhat.rhel_system_roles==1.20.5 and its role dependencies against the selected base image, generating the equivalent of a requirements.yml and bindep.txt under the hood — without you touching either file. Pinning the version (1.20.5) rather than leaving it floating keeps the resulting image reproducible across rebuilds, which matters once the EE is referenced by name in job templates across a team.

Notes / Gotchas

  • Collections resolved from GitHub in the picker are pulled at build time; if the repository moves or access changes, later rebuilds of the same EE definition can fail even though nothing in your job template changed.
  • Version pinning matters: an unpinned collection can silently pick up a newer release on the next build and change role behavior (new variable defaults, deprecated parameters) without any change to your playbooks.
  • Advanced Configuration additions (system packages, Python requirements, custom build steps) are stored with the EE definition, so they survive a rebuild — but they're easy to forget when auditing why an image is larger than expected.
  • Every EE definition built this way lands in the portal's searchable catalog, listed with owner, tags, and star/edit/delete actions, so name and tag it clearly at Step 3 rather than leaving defaults.

Step 2 is the one decision point that determines whether your playbooks will actually have the modules and roles they call — get the collection and version right here, and the rest of the wizard is just packaging and publishing.

References

All Tutorials