Automation

Pro Tips for Using Ansible Builder v3

Note: This post was updated by the Level Up team on 8/9/2024.

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.11 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:
    • Upgrade pip (currently 24.2): pip3 install pip --upgrade
    • Install Ansible Builder (Level Up recommends v.3.0.0 and no later as of this writing): pip3 install ansible-builder==3.0.0.

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 “vmware-ee”:

Create a Definition File:

This file should specify base image, system packages, python dependencies, and ansible collections that need to be included in your EE. 

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

images:
  base_image:
    name: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel8:latest

dependencies:
  galaxy:
    collections:
      - name: community.vmware
      - name: vmware.vmware_rest

  python:
    - aiohttp
    - 'git+https://github.com/vmware/vsphere-automation-sdk-python.git ; python_version >= ''2.7''  # Python 2.6 is not supported'
    - pyVmomi>=6.7.1

  system: 
    - gcc [compile platform:centos-8 platform:rhel-8]

options:
  package_manager_path: /usr/bin/microdnf

Run the Build: From within the “vmware-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 vmware-ee]$ ansible-builder build -t vmware-ee:latest
Running command:
  podman build -f context/Containerfile -t vmware-ee:latest context
Complete! The build context can be found at: /home/vagrant/vmware-ee/context
(ansible-builder-venv) [vagrant@rhel9 vmware-ee]$

Verifying You See the Image Locally

# you'll see something like this upon success:
(ansible-builder-venv) [vagrant@rhel9 vmware-ee]$ podman images | grep vmware-ee
localhost/vmware-ee                       latest             731c25776161  2 minutes ago   422 MB
(ansible-builder-venv) [vagrant@rhel9 vmware-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 vmware-ee:latest

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>/vmware-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 Your New Custom EE to AAP:
    • In AAP, navigate to Execution Environments in the sidebar and add your new vmware-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 Your New Custom EE in an AAP Job Template:
    • When creating or editing a test job template, select your new vmware-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!