Chapter 2. Using Ansible Builder
Ansible Builder is a command line tool that automates the process of building automation execution environments by using metadata defined in various Ansible Collections or created by the user.
2.1. Why use 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, collections, requirements, and system level packages. This allows you to fulfill all of the necessary requirements and dependencies to get jobs running.
2.2. 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 ansible-builder.
Procedure
In your terminal, run the following command to install Ansible Builder and activate your Ansible Automation Platform repo:
# dnf install --enablerepo ansible-automation-platform-2.2-for-rhel-8-x86_64-rpms ansible-builder
2.3. Building a definition file
Once you have Ansible Builder installed, you can create a definition file that Ansible Builder uses 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 created is in yaml format and contains different sections. For more information about the definition file content, see Breakdown of definition file content.
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" dependencies: 2 galaxy: requirements.yml python: requirements.txt system: bindep.txt additional_build_steps: 3 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, see Breakdown of definition file content.
2.4. Executing the build and creating commands
Prerequisites
- You have created a definition file
Procedure
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 -f flag:
$ ansible-builder build -f definition-file-name.ymlwhere definition-file-name specifies the name of your definition file.
2.5. Breakdown of definition file content
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.
2.5.1. Build args and base image
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:
| Value | Description |
|---|---|
|
| Allows the user to pass arbitrary arguments to the ansible-galaxy CLI during the collection installation phase. For example, the –pre flag to enable the installation of pre-release collections, or -c to disable verification of the server’s SSL certificate. |
|
| 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. This is typically a supported execution environment base image such as ee-minimal or ee-supported, but it can also be an execution environment image that you have created previously and want to customize further.
The default image is |
|
|
Specifies the intermediate builder image used for Python dependency collection and compilation; must contain a matching Python version with
The default image is |
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.5.2. Ansible config file path
The ansible_config directive allows specifying the path to an ansible.cfg file to pass a token and other settings for a private account to an automation hub server during the Collection installation stage of the build. The config file path should be relative to the definition file location, and will be copied to the generated container build context.
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
For more information on how to download a collection from automation hub, please see the related Ansible documentation page.
2.5.3. Dependencies
To avoid issues with your automation execution environment image, make sure that the entries for Galaxy, Python, and system point to a valid requirements file.
2.5.3.1. Galaxy
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: - community.aws - kubernetes.core
2.5.3.2. Python
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
2.5.3.3. System
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 can be listed as a relative path from the directory of the automation execution environment definition’s folder, or an absolute path. A minimum expectation is that the collection(s) specify necessary requirements for [platform:rpm].
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]
Entries from multiple collections are combined into a single file. This is processed by bindep and then passed to dnf. Only requirements with no profiles or no runtime requirements will be installed to the image.
2.5.4. Additional custom build steps
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
prepend: | RUN whoami RUN cat /etc/os-release
a list
Example 2.7. A list entry
append: - RUN echo This is a post-install command! - RUN ls -la /etc
2.6. Optional build command arguments
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 do not use -t with build, an image called ansible-execution-env` is created and loaded into the local container registry.
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
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.
2.7. Containerfile
Once your definition file is created, Ansible Builder reads and validates it, then creates a Containerfile, and finally passes the Containerfile to Podman to package and create your automation execution environment image using the following instructions:
- Fetch base image
- In the ephemeral copy of base image, collections are downloaded and the list of declared Python and system dependencies, if any, are collected for later.
- In the ephemeral builder image, Python wheels for all Python dependencies listed in the definition file are downloaded and built (as needed), including all Python dependencies declared by collections listed in the definition file.
-
prependfor additional_build_steps from the definition file are run. - In the final automation execution environments image, system dependencies listed in the definition file are installed, including all system dependencies declared by collections listed in the definition file.
- In the final automation execution environments image, the downloaded collections are copied and the previously fetched Python dependencies are installed.
-
appendfor additional_build_steps from the definition file are run.
2.8. Creating a Containerfile without building an image
To create a shareable Containerfile without building an image from it, run:
$ ansible-builder create
