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 ansible-builder
.
Procedure
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
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.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
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 |
---|---|
|
|
| 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.
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.4.3. Dependencies
2.4.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: - geerlingguy.java - kubernetes.core
2.4.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.4.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 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]
2.4.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
RUN whoami RUN cat /etc/os-release
a list
Example 2.7. A list entry
- RUN echo This is a post-install command! - RUN ls -la /etc
2.5. Optional build command arguments
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
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.6. Creating a Containerfile without building an image
To create a shareable Containerfile
without building an image from it, run:
$ ansible-builder create