Ansible Builder Guide
Execution environment builder to create consistent and reproducible automation execution environments for your Red Hat Ansible Automation Platform.
Use Ansible Builder to create consistent and reproducible automation execution environments for your Red Hat Ansible Automation Platform needs.
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Chapter 1. Introduction to Ansible Builder
1.1. About Ansible Builder
Ansible Builder is a command line tool that automates the process of building automation execution environments by using the metadata defined in various Ansible Collections, as well as by the user.
1.1.1. Why use Ansible Builder?
Before Ansible Builder was developed, Automation Platform users would potentially run against dependency issues and multiple error messages as they attempted to create a custom virtual environment or container that had all of their required dependencies installed.
Through the use of an easily customizable definition file, Ansible Builder installs Ansible, specified Collections and any of its dependencies so that all of the necessary requirements to get jobs running are fulfilled behind the scenes.
Chapter 2. Using Ansible Builder
2.1. Installing Ansible Builder
You can install Ansible Builder using Red Hat Subscription Management (RHSM) to attach your Red Hat Ansible Automation Platform subscription. Attaching your Red Hat Ansible Automation Platform subscription allows you to access subscription-only resources necessary to install
ansible-builder. Once you attach your subscription, the necessary repository for
ansible-builder is automatically enabled.
You must have valid subscriptions attached on the host before installing
In your terminal, run the following command to activate your Ansible Automation Platform repo:
$ dnf config-manager --enable ansible-automation-platform-2.1-for-rhel-8-x86_64-rpms
Then enter the following command to install Ansible Builder:
$ dnf install ansible-builder
2.2. Building a definition file
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
For more information about these definition file parameters, please see this section.
2.3. Executing the build and creating commands
- You have created a definition file
To build an automation execution environment image, run:
$ ansible-builder build
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
$ ansible-builder build -f definition-file-name.yml
where definition-file-name specifies the name of your definition file.
2.4. Breakdown of definition file content
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
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
| || |
| || |
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
| || |
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.
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
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.
ansible.cfg file should be formatted like the following example:
Example 2.2. An
[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
For more information on how to download a collection from automation hub, please see the related Ansible documentation page.
galaxy entry points to a valid requirements file for the
ansible-galaxy collection install -r … command.
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
python entry in the definition file points to a valid requirements file for the
pip install -r … command.
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
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
subversion packages to a container:
Example 2.5. A
libxml2-devel [platform:rpm] subversion [platform:rpm]
2.4.4. Additional custom build steps
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
Example 2.7. A list entry
- RUN echo This is a post-install command! - RUN ls -la /etc
2.5. Optional build command arguments
-t flag will give your automation execution environment image a specific name. For example, the following command will build an image named
$ ansible-builder build -t my_first_ee_image
If you have multiple definition files, you can specify which one to use by utilizing the
$ ansible-builder build -f another-definition-file.yml -t another_ee_image
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
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.
2.6. Creating a Containerfile without building an image
To create a shareable
Containerfile without building an image from it, run:
$ ansible-builder create
Chapter 3. Publishing an automation execution environment
3.1. Pushing an execution environment container image to automation hub
- You have execution environment permissions in automation hub allowing you to create new containers or push to an existing container.
A container registry is a repository for storing container images. Once you have built an automation execution environment image, you’ll be ready to push that container image to the registry portion of your instance of automation hub.
With your automation hub URL on hand, run the following command to log in to Podman, substituting your username, password, and automation hub URL:
$ podman login -u=username -p=password automation-hub-url
Once you’re logged in to Podman, run the following command to push your container image to the container registry on automation hub:
$ podman push automation-hub-url/ee-image-name
The automation execution environment image name is specified by the
-t argument to the
ansible-builder build command. If you did not specify a custom image name using the
-t flag, the default image tag is
3.2. Pulling from a protected registry
To pull container images from a password or token-protected registry, create a credential in automation controller:
- Navigate to automation controller.
- In the side-menu bar, click Resources → Credentials.
- Click Add to create a new credential.
- Supply an authorization URL, username, and password. Click Save.
For more information, please reference the Pulling from Protected Registries section of the Execution Environment documentation.
Chapter 4. Building off of existing base EEs provided by Red Hat Ansible Automation Platform
4.1. Gathering system-level dependencies
bindep format provides a way of specifying cross-platform requirements. A minimum expectation is that the collection(s) specify necessary requirements for
Below is an example of content from a valid
Example 4.1. A
python38-devel [platform:rpm compile] subversion [platform:rpm] git-lfs [platform:rpm]
Entries from multiple collections will be combined into a single file. This will be processed by
bindep and then passed to
dnf. Only requirements with no profiles or no runtime requirements will be installed to the image.
4.2. Customizing an existing execution environment image
Ansible Controller ships with three default execution environments:
Ansible 2.9- no collections are installed other than Controller modules
Minimal- contains the latest Ansible 2.12 release along with Ansible Runner, but contains no collections or other additional content
EE Supported- contains all Red Hat-supported content
While these environments cover many automation use cases, you can add additional items to customize these containers for your specific needs. The following procedure adds the
kubernetes.core collection to the
ee-minimal default image:
Log in to
$ podman login -u="[username]" -p="[token/hash]" registry.redhat.io
Pull an Automation Execution Environment image
podman pull registry.redhat.io/ansible-automation-platform-21/ee-minimal-rhel8:latest
Configure your Ansible Builder files to specify any additional content to add to the new execution environment image which is based off of
For example, to add the Kubernetes Core Collection from Galaxy to the image, fill out the
requirements.ymlfile as such:
collections: - kubernetes.core
- For more information on definition files and their content, refer to to definition file breakdown section.
In the execution environment definition file, specify the filepath to the original
ee-minimalcontainer in the
EE_BASE_IMAGEfield. In doing so, your final
execution-environment.ymlfile will look like the following:
Example 4.2. A customized
version: 1 build_arg_defaults: EE_BASE_IMAGE: 'example.registry.com/my-base-ee' dependencies: galaxy: requirements.ymlNote
Since this example uses the community version of
kubernetes.coreand not a certified collection from automation hub, we do not need to create an
ansible.cfgnor reference that in our definition file.
Build the new execution environment image using the following command:
$ ansible-builder build -t registry.redhat.io/[username]/new-ee
[username]specifies your username, and
new-eespecifies the name of your new container image.
podman imagescommand to confirm that your new container image is in that list:
Example 4.3. Output of a
podman imagescommand with the image
REPOSITORY TAG IMAGE ID CREATED SIZE localhost/new-ee latest f5509587efbb 3 minutes ago 769 MB
- Verify your newly-created execution environment image via Ansible Navigator
Tag the image for use in your automation hub:
$ podman tag registry.redhat.io/_[username]_/_new-ee_ [automation-hub-IP-address]/_[username]_/_new-ee_
Log in to your automation hub using Podman:Note
You must have
adminor appropriate container repository permissions for automation hub to push a container. See Managing containers in private automation hub in the Red Hat Ansible Automation Platform documentation for more information.
$ podman login -u="[username]" -p="[token/hash]" [automation-hub-IP-address]
Push your image to the container registry in automation hub:
$ podman push [automation-hub-IP-address]/_[username]_/_new-ee_
Pull your new image into your automation controller instance:
- Navigate to automation controller.
- From the side-navigational bar, click Administration → Execution Environments.
- Click Add.
Enter the appropriate information then click Save to pull in the new image.Note
if your instance of automation hub is password or token protected, ensure that you have the appropriate container registry credential set up.