Ansible Builder version 3 Porting Guide
This section discusses the behavioral changes between ansible-builder
version 1.2 and version 3.0.
We suggest you read this page along with ansible-builder 3.0 release notes to understand what updates you may need to make.
Topics
Overview
The Ansible Builder 3.x execution environment definition file accepts seven top-level sections:
additional_build_files
additional_build_steps
build_arg_defaults
dependencies
images
options
version
Porting options
You need to change the configuration YAML keys in your older (v1 and v2) execution environment file to the one listed here.
additional_build_files
This is a new configuration that can be used to specify files to be added to the build context directory. These can then be referenced or copied by additional_build_steps during any build stage.
See the additional_build_files section for more details.
additional_build_steps
With Ansible Builder 3, you can specify more fine-grained build steps or custom commands for any build phase. These commands will be inserted directly into the build instruction file for the container runtime (For example, Containerfile or Dockerfile). The commands must conform to any rules required by the containerization tool.
These are additional build steps -
prepend_base
append_base
prepend_galaxy
append_galaxy
prepend_builder
append_builder
prepend_final
append_final
See the additional_build_steps section for more details.
dependencies
Specifies dependencies to install into the final image, including ansible-core
, ansible-runner
, Python packages, system packages, and Ansible Collections. Ansible Builder automatically installs dependencies for any Ansible Collections you install.
In general, you can use standard syntax to constrain package versions. Use the same syntax you would pass to dnf
, pip
, ansible-galaxy
, or any other package management utility. You can also define your packages or collections in separate files and reference those files in the dependencies
section of your execution environment definition file.
The following keys are valid for this section:
ansible_core
ansible_runner
galaxy
python
python_interpreter
system
See the dependencies section for more details.
images
Specifies the base image to be used. At a minimum you MUST specify a source, image, and tag for the base image. The base image provides the operating system and may also provide some packages. We recommend using the standard host/namespace/container:tag
syntax to specify images.
See the images section for more details.
image verification
You can verify signed container images if you are using the podman
container
runtime.
See the image verification section for more details.
options
A dictionary of keywords/options that can affect builder runtime functionality. Valid keys for this section are:
container_init
cmd
entrypoint
package_pip
package_manager_path
skip_ansible_check
relax_passwd_permissions
workdir
user
tags
See the options section for more details.
version
Must be 3
if you are using Ansible Builder 3.x.
See the version section for more details.