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.
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 execution environment definition’s folder, or an absolute path.
The python entry points to a valid requirements file for the
pip install -r ... command.
requirements.txt may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
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
The following options can be used with the
ansible-builder build command:
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 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
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:
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
bindep format provides a way of specifying cross-platform requirements. A minimum expectation is that collections specify necessary requirements for
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.