Execution Environment Definition¶
The execution environment (EE) definition file supports multiple versions.
Version 1: Supported by all
ansible-builder
versions.Version 2: Supported by
ansible-builder
versions1.2
and higher.
Version 2 adds the capability to optionally use and verify
signed container images. This feature is only supported with the podman
container runtime.
If the EE file does not specify a version, version 1 will be assumed.
Version 1 Format¶
An example version 1 execution environment definition schema is as follows:
---
version: 1
build_arg_defaults:
EE_BASE_IMAGE: 'quay.io/ansible/ansible-runner:latest'
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
The following keys are supported in this version of the EE file:
version¶
This integer value defines the version of the EE file. If not specified, the
default of 1
will be used.
build_arg_defaults¶
Default values for build args can be specified in the definition file in
the build_arg_defaults
section as a dictionary. This is an alternative
to using the --build-arg
CLI flag.
Build args used by ansible-builder
are the following:
ANSIBLE_GALAXY_CLI_COLLECTION_OPTS
This allows the user to pass the ‘–pre’ flag (or others) to enable the installation of pre-releases collections.
ANSIBLE_GALAXY_CLI_ROLE_OPTS
This allows the user to pass the flags to the Role installation.
EE_BASE_IMAGE
This string value specifies the parent image for the execution environment.
EE_BUILDER_IMAGE
This string value specifies the image used for compiling type tasks.
Values given inside of build_arg_defaults
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.
ansible_config¶
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.
dependencies¶
This section is a dictionary value that is used to define the Ansible Galaxy, Python, and system dependencies that must be installed into the final container. Valid keys for this section are:
galaxy
This string value is the path to a file containing the Ansible Galaxy dependencies to be installed with the
ansible-galaxy collection install -r ...
command.The supplied value may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
python
This string value is the path to a file containing the Python dependencies to be installed with the
pip install -r ...
command.The supplied value may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
system
This string value is points to a bindep requirements file. This will be processed by
bindep
and then passed todnf
, other platforms are not yet supported.
additional_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 list (as shown via
append
)
Version 2 Format¶
With the version 2 format, an execution environment definition may specify a base and builder container image whose signature must be validated before builder will build the resulting image, based on the value of the --container-policy CLI option.
Note
Although builder will create a policy.json file (see below) to control Podman image validation, it is up to the user to properly configure the Podman runtime to talk to the registries needed. This may include defining the sigstore for each registry, using secure connections (or not), etc. Such configuration is beyond the scope of this document.
This format is identical to the version 1 format, except for the following changes:
A new
images
key is added that supports more complex definitions of the base and builder images.Defining
EE_BASE_IMAGE
orEE_BUILDER_IMAGE
in thebuild_args_defaults
section, or with the --build-arg CLI option, is no longer allowed.
An example version 2 execution environment definition schema is as follows:
---
version: 2
build_arg_defaults:
ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: '--pre'
ansible_config: 'ansible.cfg'
dependencies:
galaxy: requirements.yml
python: requirements.txt
system: bindep.txt
images:
base_image:
name: registry.redhat.io/ansible-automation-platform-21/ee-minimal-rhel8:latest
builder_image:
name: my-mirror.example.com/aap-mirror/ansible-builder-rhel8:latest
signature_original_name: registry.redhat.io/ansible-automation-platform-21/ansible-builder-rhel8:latest
images¶
This section is a dictionary that is used to define the base and builder images. How this data is used in relation to a Podman policy.json file for container image signature validation depends on the value of the --container-policy CLI option.
ignore_all
policy: Generate a policy.json file in the build context directory where no signature validation is performed. This duplicates the functionality under the version 1 format.
system
policy: Signature validation is performed using pre-existing policy.json files in standard system locations.ansible-builder
assumes no responsibility for the content within these files, and the user has complete control over the content.
signature_required
policy:ansible-builder
will use the container image definitions here to generate a policy.json file in the build context directory that will be used during the build to validate the images.
Valid keys for this section are:
base_image
A dictionary defining the parent image for the execution environment. A
name
key must be supplied with the container image to use. Use thesignature_original_name
key if the image is mirrored within your repository, but signed with the original image’s signature key. Image names MUST contain a tag, such as:latest
.builder_image
A dictionary defining the image used for compiling type tasks. A
name
key must be supplied with the container image to use. Use thesignature_original_name
key if the image is mirrored within your repository, but signed with the original image’s signature key. Image names MUST contain a tag, such as:latest
.