This section contains reference information associated with setting up and building execution environments.
A definition file is a .yml
file that is required to build an image for an execution environment. An example of an execution environment definition schema is as follows:
---
version: 1
build_arg_defaults:
EE_BASE_IMAGE: 'quay.io/ansible/ansible-runner:stable-2.10-devel'
ansible_config: 'ansible.cfg'
dependencies:
galaxy: requirements.yml
python: requirements.txt
system: bindep.txt
additional_build_steps:
prepend: |
RUN whoami
RUN cat /etc/os-release
append:
- RUN echo This is a post-install command!
- RUN ls -la /etc
Default values for build arguments can be specified in the definition file in the default_build_args
section as a dictionary. This is an alternative to using the --build-arg
CLI flag.
Build arguments used by ansible-builder
are the following:
ANSIBLE_GALAXY_CLI_COLLECTION_OPTS
allows the user to pass the –pre
flag to enable the installation of pre-releases collections.
EE_BASE_IMAGE
specifies the parent image for the execution environment.
EE_BUILDER_IMAGE
specifies the image used for compiling type tasks.
Values given inside of default_build_args
will be hard-coded into the Containerfile, so they 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.
When using an ansible.cfg
file to pass a token and other settings for a private account to an Automation Hub server, listing the config file path here (as a string) will enable it to be included as a build argument in the initial phase of the build.
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 execution environment definition’s folder, or an absolute path.
The python entry points to a valid requirements file for the pip install -r ...
command.
The entry requirements.txt
may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
The system
entry points to a bindep
requirements file. This will be processed by bindep
and then passed to dnf
, other platforms are not yet supported. For more information about bindep, refer to the OpenDev documentation.
Additional commands may be specified in the additional_build_steps
section, either for before the main build steps (prepend
) or after (append
). The syntax needs to be one of the following:
a multi-line string (example shown in the prepend
section above)
a dictionary (as shown via append
)
The following options can be used with the ansible-builder build
command:
Flag |
Description |
Syntax |
|
To customize the tagged name applied to the built image |
|
|
To use a definition file named something other than |
|
|
To specify a location other than the default directory named |
|
|
To use Podman or Docker’s build-time variables, specify them the same way you would with |
|
To use a custom base image
(replaces previously discontinued |
|
|
|
To use Docker to build images instead of the Podman default |
|
|
To customize the level of verbosity |
|
The example in test/data/pytz
requires the awx.awx
collection in the execution environment definition. The lookup plugin awx.awx.tower_schedule_rrule
requires the PyPI pytz
and another library to work. If test/data/pytz/execution-environment.yml
file is provided to the ansible-builder build
command, then it will install the collection inside the image, read the requirements.txt
file inside of the collection, and then install pytz
into the image.
The image produced can be used inside of an ansible-runner
project by placing these variables inside the env/settings
file, inside of the private data directory.
---
container_image: image-name
process_isolation_executable: podman # or docker
process_isolation: true
The awx.awx
collection is a subset of content included in the default AWX execution environment. More details can be found in the awx-ee repository.
Collections inside of the galaxy
entry of an execution environment will contribute their Python and system requirements to the image.
Requirements from a collection can be recognized in these ways:
A file meta/execution-environment.yml
references the Python and/or bindep requirements files
A file named requirements.txt
is in the root level of the collection
A file named bindep.txt
is in the root level of the collection
If any of these files are in the build_ignore
of the collection, it will not work correctly.
Collection maintainers can verify that ansible-builder recognizes the requirements they expect by using the introspect
command, for example:
ansible-builder introspect --sanitize ~/.ansible/collections/
Python requirements files are combined into a single file using the requirements-parser
library in order to support complex syntax like references to other files.
Entries from separate collections that give the same package name will be combined into the same entry, with the constraints combined.
There are several package names which are specifically ignored by ansible-builder, meaning that if a collection lists these, they will not be included in the combined file. These include test packages and packages that provide Ansible itself. The full list can be found in EXCLUDE_REQUIREMENTS
in the ansible_builder.requirements
module.
The bindep
format provides a way of specifying cross-platform requirements. A minimum expectation is that collections specify necessary requirements for [platform:rpm]
.
Entries from multiple collections will be combined into a single file. Only requirements with no profiles (runtime requirements) will be installed to the image. Entries from multiple collections which are outright duplicates of each other may be consolidated in the combined file.