Chapter 2. Using Ansible Builder

Before Ansible Builder was developed, Red Hat Ansible Automation Platform users could run into dependency issues and errors when creating custom virtual environments or containers that included all of the required dependencies installed.

Now, with Ansible Builder, you can easily create a customizable automation execution environments definition file that specifies the content you want included in your automation execution environments such as Ansible Core, Python, Collections, third-party Python requirements, and system level packages. This allows you to fulfill all of the necessary requirements and dependencies to get jobs running.

After you install Ansible Builder, you can create a definition file that Ansible Builder uses to create your automation execution environment image. Ansible Builder makes an automation execution environment image by reading and validating your definition file, then creating a Containerfile, and finally passing the Containerfile to Podman, which then packages and creates your automation execution environment image. The definition file that you create must be in yaml format and contain different sections. The default definition filename, if not provided, is execution-environment.yml. For more information on the parts of a definition file, see Breakdown of definition file content.

The following is an example of a version 3 definition file. Each definition file must specify the major version number of the Ansible Builder feature set it uses. If not specified, Ansible Builder defaults to version 1, making most new features and definition keywords unavailable.

version: 3

build_arg_defaults: 1
  ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: '--pre'

dependencies: 2
  galaxy: requirements.yml
  python:
    - six
    - psutil
  system: bindep.txt

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

# Custom package manager path for the RHEL based images
 options: 4
 package_manager_path: /usr/bin/microdnf

additional_build_steps: 5
  prepend_base:
    - RUN echo This is a prepend base command!

  prepend_galaxy:
    # Environment variables used for Galaxy client configurations
    - ENV ANSIBLE_GALAXY_SERVER_LIST=automation_hub
    - ENV ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_URL=https://console.redhat.com/api/automation-hub/content/xxxxxxx-synclist/
    - ENV ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_AUTH_URL=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
    # define a custom build arg env passthru - we still also have to pass
    # `--build-arg ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN` to get it to pick it up from the env
    - ARG ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN

  prepend_final: |
    RUN whoami
    RUN cat /etc/os-release
  append_final:
    - RUN echo This is a post-install command!
    - RUN ls -la /etc

After you create a definition file, you can proceed to build an automation execution environment image.

$ ansible-builder build

By default, Ansible Builder looks for a definition file named execution-environment.yml but a different file path can be specified as an argument with the -f flag:

$ ansible-builder build -f definition-file-name.yml

where definition-file-name specifies the name of your definition file.

A definition file is required for building automation execution environments with Ansible Builder, because it specifies the content that is included in the automation execution environment container image.

The following sections breaks down the different parts of a definition file.

collections:
  - community.aws
  - kubernetes.core

boto>=2.49.0
botocore>=1.12.249
pytz
python-dateutil>=2.7.0
awxkit
packaging
requests>=2.4.2
xmltodict
azure-cli-core==2.11.1
openshift>=0.6.2
requests-oauthlib
openstacksdk>=0.13
ovirt-engine-sdk-python>=4.4.10

libxml2-devel [platform:rpm]
subversion [platform:rpm]

prepend_final: |
   RUN whoami
   RUN cat /etc/os-release

append_final:
- RUN echo This is a post-install command!
- RUN ls -la /etc

The -t flag will tag your automation execution environment image with a specific name. For example, the following command will build an image named my_first_ee_image:

$ ansible-builder build -t my_first_ee_image

If you have multiple definition files, you can specify which one to use by including the -f flag:

$ ansible-builder build -f another-definition-file.yml -t another_ee_image

In this example, Ansible Builder will use the specifications provided in the file named another-definition-file.yml instead of the default execution-environment.yml to build an automation execution environment image named another_ee_image.

For other specifications and flags that you can use with the build command, enter ansible-builder build --help to see a list of additional options.

After your definition file is created, Ansible Builder reads and validates it, creates a Containerfile and container build context, and optionally passes these to Podman to build your automation execution environment image. The container build occurs in several distinct stages: base , galaxy, builder, and final. The image build steps (along with any corresponding custom prepend_ and append_ steps defined in additional_build_steps) are:

If you are required to use shared container images built in sandboxed environments for security reasons, you can create a shareable Containerfile.

$ ansible-builder create