Pro Tips for Using Ansible Builder v3

Hey there! If you’re looking to truly star in the Ansible game, we need to talk about Ansible Builder v3. This powerhouse CLI tool is your gateway to creating custom execution environment images, which will completely redefine the boundaries of what’s possible for you and your team to achieve with your investment in Red Hat Ansible Automation Platform (AAP).

While “execution environment image” may sound like an awful a lot of syllables to refer to something new and complex that you’ll have to learn a bunch about when you’re just trying to automate some switches right now, it’s really not! An EE, as it’s often called, is really just a regular old container, that comes from a container image, that AAP runs as a container instance, to automate jobs on all of the hosts it manages. (Ansible Navigator can use EE’s too BTW!) Starting in AAP 2.x, the controller nodes/execution nodes actually always use EE’s, they just use the ones that AAP installs for us by default… until you need some specific Python libraries, or system dependencies, or both, to support the Ansible Collections and other functions you may want in order to fully integrate everything in your organization (network OEM collections like Cisco’s are fairly common in requiring additional Python lib’s at a minimum). At which point, you’ll need at least one custom EE, and so you’ll also need to learn how to work a bit with the friendly and super helpful Ansible Builder. This is one of those Ansible topics that is actually sometimes harder to talk about conceptually than it is to just show it in action, so let’s dive right in.

Getting Started with Ansible Builder

We’ll first set up Ansible Builder in a fresh Python virtual environment. This will ensure that your Python setup is clean and tailored just for you:

  1. Install Python pip and Podman (Which We’ll Need Shortly):
    • Run sudo dnf install python3-pip podman on recent versions of RHEL-based systems (this post assumes you have something like Python 3.9 installed).
    • Create a new virtual environment: python3 -m venv ansible-builder-venv.
    • Activate the environment: source ansible-builder-venv/bin/activate.
  2. Once Inside the Python Virtualenv, Install Ansible Builder:
    • Simply run pip3 install ansible-builder.

Defining and Building Your Custom Execution Environment

With your environment ready, we can now define and build your first custom Execution Environment (EE) in a new folder called something like “network-ee”:

Create a Definition File:

execution-environment.yml. This file should specify base images, system packages, python dependencies, and ansible collections that need to be included in your EE.

(Note that “system: bindep.txt” is commented out in this example. If a package like “gcc” were given as a requirement for a given collection, it would be defined in bindep.txt– and of course uncommented at that point.)

# execution-environment.yml:
---
version: 1

build_arg_defaults:
  EE_BASE_IMAGE: 'quay.io/ansible/ansible-runner:stable-2.10-devel'

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

Define Your Python Dependencies:

requirements.txt, which includes libraries like ciscoisesdk, requests, and pan-os-python, ensure they’re listed under Python dependencies in your execution-environment.yml.

# requirements.txt:
ciscoisesdk
requests
pan-os-python

Define Your Collections to Install:

requirements.yml, which is the whole point of creating a custom EE, because these Ansible Collections depend on Python libraries to work correctly!

# requirements.yml:
---
collections:
  - arista.eos
  - cisco.nxos
  - infoblox.nios_modules
  - logicmonitor.integration

Run the Build: From within the “network-ee” directory, execute ansible-builder build, which will compile all the specified elements into a new EE. (This may take a few minutes.)

# you'll see something like this upon success:
(ansible-builder-venv) [vagrant@rhel9 network-ee]$ ansible-builder build -t network-ee
Running command:
  podman build -f context/Containerfile -t network-ee context
Complete! The build context can be found at: /home/vagrant/network-ee/context
(ansible-builder-venv) [vagrant@rhel9 network-ee]$ 

Verifying You See the Image Locally

# you'll see something like this upon success:
(ansible-builder-venv) [vagrant@rhel9 network-ee]$ podman images | grep network-ee
localhost/network-ee                       latest             05b041692d6b  2 minutes ago   1.05 GB
(ansible-builder-venv) [vagrant@rhel9 network-ee]$ 

Testing the EE with Ansible Navigator (Optional)

See also: https://levelupla.io/a-blazingly-fast-ansible-navigator-tutorial/

# test.yml:
- name: Test Playbook
  hosts: localhost
  connection: local
  tasks:
    - ansible.builtin.ping:

ansible-navigator run test.yml -m stdout --eei network-ee

Pushing the EE to Quay.io

Once your EE is built, it’s time to share it publicly with the world (or at least privately with your team), by pushing it to Quay.io:

  1. Login to Quay.io (free to sign up – but Docker Hub also works!):
    • podman login quay.io – Enter your credentials to establish a connection.
  2. Push Your EE:
    • podman push quay.io/<your-username>/network-ee:latest.

Deploying with AAP

See also: https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html#use-an-execution-environment-in-jobs

Finally, to deploy this EE with an Ansible Automation Platform job template:

  1. Add Custom EE to AAP:
    • In AAP, navigate to Execution Environments in the sidebar and add your new network-ee using the URL-looking string that Quay.io gives you (note that it doesn’t use an “https://” prefix). If not public, you’ll also need to add some Quay.io Credentials.
  2. Use EE in a Job Template:
    • When creating or editing a test job template, select your new network-ee in the Execution Environment field.

That’s all there is to it! With these simple steps, you’ve not only enhanced your automation capabilities but also tailored Red Hat Ansible to fit your team’s exact needs, pretty much regardless of the hardware OEM logos decorating in your datacenter racks. Imagine the many, many possibilities ahead.

Spread the word. Share this post!