Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Using Ansible Builder

2.1. Installing Ansible Builder
Copy link

You can install Ansible Builder using Red Hat Subscription Management to register and attach to your Red Hat Ansible Automation Platform subscription. In your terminal, run the following command: 

$ dnf install ansible-builder
Copy to Clipboard Toggle word wrap

You can also install Ansible Builder from the Python Package Index (PyPI). To install with this setup, run: 

$ pip install ansible-builder
Copy to Clipboard Toggle word wrap

2.2. Building a definition file
Copy link

Once you have Ansible Builder installed, we will need to create a definition file which Ansible Builder will use to create your automation execution environment image. The high level process to build an automation execution environment image is for Ansible Builder to read and validate your definition file, then create a Containerfile, and finally pass the Containerfile to Podman which then packages and creates your automation execution environment image. The definition file we will create for Ansible Builder is in yaml format and contains different sections which we will discuss in further detail.

The following is an example of a definition file:

Example 2.1. A definition file

version: 1

build_arg_defaults:
1 

  ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: "-v"

ansible_config: 'ansible.cfg'
2 


dependencies:
3 

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

additional_build_steps:
4 

  prepend: |
    RUN whoami
    RUN cat /etc/os-release
  append:
    - RUN echo This is a post-install command!
    - RUN ls -la /etc
Copy to Clipboard Toggle word wrap
1
Lists default values for build arguments
2
Specifies the ansible.cfg file path
3
Specifies the location of various requirements files
4
Commands for additional custom build steps

For more information about these definition file parameters, please see this section.

2.3. Executing the build and creating commands
Copy link

Prerequisites

  • You have created a definition file

Procedure

To build an automation execution environment image, run: 

$ ansible-builder build
Copy to Clipboard Toggle word wrap

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

$ ansible-builder build -f definition-file-name.yml
Copy to Clipboard Toggle word wrap

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

2.4. Breakdown of definition file content
Copy link

A definition file is necessary for building automation execution environments with Ansible Builder, as it specifies the content which will be included in the automation execution environment container image.

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

2.4.1. Build args and base image
Copy link

The build_arg_defaults section of the definition file is a dictionary whose keys can provide default values for arguments to Ansible Builder. See the following table for a list of values that can be used in build_arg_defaults:

Expand
ValueDescription

ANSIBLE_GALAXY_CLI_COLLECTION_OPTS

  • Allows the user to pass the –pre flag to enable the installation of pre-releases collections
  • -c is the equivalent of setting verify_ssl to false

EE_BASE_IMAGE

Specifies the parent image for the automation execution environment, enabling a new image to be built that is based off of an already-existing image

EE_BUILDER_IMAGE

Specifies the image used for compiling-type tasks

The values given inside build_arg_defaults will be hard-coded into the Containerfile, so these values will persist if podman build is called manually.

Note

If the same variable is specified in the CLI --build-arg flag, the CLI value will take higher precedence.

2.4.2. Ansible config file path
Copy link

When using an ansible.cfg file to pass a token and other settings for a private account to an automation hub server, list the config file path (relative to where the definition file is located) as a string to enable it as a build argument in the initial phase of the build.

The ansible.cfg file should be formatted like the following example:

Example 2.2. An ansible.cfg file

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=my_ah_token
Copy to Clipboard Toggle word wrap

For more information on how to download a collection from automation hub, please see the related Ansible documentation page.

2.4.3. Dependencies
Copy link

2.4.3.1. Galaxy
Copy link

The galaxy entry points to a valid requirements file for the ansible-galaxy collection install -r …​ command.

The entry requirements.yml may be a relative path from the directory of the automation execution environment definition’s folder, or an absolute path.

The content of a requirements.yml file may look like the following:

Example 2.3. A requirements.yml file for Galaxy

---
collections:
  - geerlingguy.java
  - kubernetes.core
Copy to Clipboard Toggle word wrap

2.4.3.2. Python
Copy link

The python entry in the definition file points to a valid requirements file for the pip install -r …​ command.

The entry requirements.txt is a file that installs extra Python requirements on top of what the Collections already list as their Python dependencies. It may be listed as a relative path from the directory of the automation execution environment definition’s folder, or an absolute path. The contents of a requirements.txt file should be formatted like the following example, similar to the standard output from a pip freeze command:

Example 2.4. A requirements.txt file for Python

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
python_version >= '2.7'
collection community.vmware
google-auth
openshift>=0.6.2
requests-oauthlib
openstacksdk>=0.13
ovirt-engine-sdk-python>=4.4.10
Copy to Clipboard Toggle word wrap

2.4.3.3. System
Copy link

The system entry in the definition points to a bindep requirements file, which will install system-level dependencies that are outside of what the collections already include as their dependencies. It may be listed as a relative path from the directory of the automation execution environment definition’s folder, or an absolute path.

To demonstrate this, the following is an example bindep.txt file that adds the libxml2 and subversion packages to a container:

Example 2.5. A bindep.txt file

libxml2-devel [platform:rpm]
subversion [platform:rpm]
Copy to Clipboard Toggle word wrap

2.4.4. Additional custom build steps
Copy link

The prepend and append commands may be specified in the additional_build_steps section. These will add commands to the Containerfile which will run either before or after the main build steps are executed.

The syntax for additional_build_steps must be one of the following:

  • a multi-line string

    Example 2.6. A multi-line string entry

    RUN whoami
RUN cat /etc/os-release
    Copy to Clipboard Toggle word wrap

  • a list

    Example 2.7. A list entry

    - RUN echo This is a post-install command!
- RUN ls -la /etc
    Copy to Clipboard Toggle word wrap

2.5. Optional build command arguments
Copy link

The -t flag will give your automation execution environment image 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
Copy to Clipboard Toggle word wrap

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

$ ansible-builder build -f another-definition-file.yml -t another_ee_image
Copy to Clipboard Toggle word wrap

In the example above, Ansible Builder will use the specifications provided in the file 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 are possible to use with the build command, enter ansible-builder build --help to see a list of additional options.

To create a shareable Containerfile without building an image from it, run: 

$ ansible-builder create
Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat