Documentation

15. Execution Environment Setup Reference

This section contains reference information associated with setting up and building execution environments.

15.1. Execution environment definition

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

15.1.1. Build arguments and base image

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.

15.1.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, 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.

15.1.3. Ansible Galaxy dependencies

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.

15.1.4. Python dependencies

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.

15.1.5. System-level dependencies

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.

15.1.6. Additional custom build steps

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)

15.2. ansible-builder build options

The following options can be used with the ansible-builder build command:

Flag

Syntax

Description

--tag

$ ansible-builder build --tag=my-custom-ee

To customize the tagged name applied to the built image.

--file

$ ansible-builder build --file=my-ee.yml

To use a definition file named something other than execution-environment.yml.

--context

$ ansible-builder build --context=/path/to/dir

To specify a location other than the default directory named context created in the current working directory.

--build-arg

$ ansible-builder build --build-arg FOO=bar

To use Podman or Docker build-time variables, specify them the same way you would with podman build or docker build. By default, the Containerfile or Dockerfile contains a build argument EE_BASE_IMAGE, that lets you rebuild without modifying files.

--build-arg

$ ansible-builder build --build-arg EE_BASE_IMAGE=registry.example.com/another-ee

To use a custom base image, replaces previously discontinued --base-image option.

--container-runtime

$ ansible-builder build --container-runtime=docker

To use Docker to build images instead of the Podman default.

--verbosity

$ ansible-builder build --verbosity 2

To customize the level of verbosity.

15.2.1. Examples

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.

15.3. Collection-level metadata

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/

15.3.1. Python Dependencies

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.

15.3.2. System-level Dependencies

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.