Ansible Builder
raw JSON → 3.1.1 verified Tue Apr 14 auth: no python
Ansible Builder is a command-line utility for configuring and building portable, consistent, and customized Ansible control nodes, known as Execution Environments, packaged as containers by Podman or Docker. These Execution Environments are used with Ansible Automation Platform components like AWX or Ansible Controller, Ansible Navigator, or for local development. The current version is 3.1.1, and it maintains an active release cadence with significant updates between major versions, especially in its definition schema.
pip install ansible-builder Common errors
error ERROR: Double requirement given ↓
cause This error occurs in ansible-builder 3.1 and later because dependency sanitization was removed. If multiple collections or user requirement files list the same Python package with potentially different version constraints, pip receives duplicate entries and fails.
fix
Review your
requirements.txt files and Ansible collection dependencies to ensure unique and compatible entries for Python packages. Consider upgrading pip within your base image to a newer version that might handle duplicate requirements more gracefully, or manually consolidate the requirements. error ansible_builder.exceptions.DefinitionError: Error: Unknown yaml key(s), {'images'}, found in the definition file. ↓
cause This error typically indicates that your `execution-environment.yml` file is using a schema from an older `ansible-builder` version (e.g., v1 or v2) while `ansible-builder` 3.x (or later) is expecting the version 3 schema, which has significantly changed structure and keywords.
fix
Update your
execution-environment.yml file to explicitly declare version: 3 at the top and adjust its structure according to the Ansible Builder 3.x schema. The images section, for instance, is part of the version 3 schema. error ERROR: Could not find a version that satisfies the requirement <package_name> ↓
cause This error means that the package manager (e.g., `pip` for Python packages, `dnf`/`yum` for system packages) inside the execution environment could not locate or resolve the specified dependency. This can be due to a typo in the package name, an unavailable version, network connectivity issues (e.g., proxies, certificate problems), or incorrect repository configuration.
fix
Verify the exact package name and version. Check network connectivity from within the build environment. If in a disconnected environment, ensure your
pip.conf or yum/dnf repository configurations correctly point to local mirrors or trusted sources, and that any necessary internal certificates are copied into the image during the build. error Error: building at STEP "RUN <command>": while running runtime: exit status 1. ↓
cause This is a generic error indicating that a command executed during one of the container build steps failed with a non-zero exit status. The specific `<command>` and preceding output usually provide more context about the underlying issue, which could range from missing dependencies to script execution failures.
fix
Re-run
ansible-builder build with increased verbosity (-vvv) to get detailed output and identify the exact command that failed and its error messages. Inspect the generated Containerfile using ansible-builder create to understand the build steps. You can then isolate the failing command and test it manually within a container based on your base image. error ERROR! Expecting requirements yaml to be a list or dictionary but got str ↓
cause This error occurs when the `execution-environment.yml` file has incorrectly formatted entries for dependencies, particularly under `galaxy`, `python`, or `system` keys. Instead of providing a list or dictionary as expected by the schema, a single string (e.g., a filename without brackets) is provided.
fix
Ensure that the dependency entries in your
execution-environment.yml are correctly formatted as lists or dictionaries, as per the schema. For example, if referencing a requirements.yml file for Galaxy collections, it should be listed as galaxy: [requirements.yml] or galaxy: { collections: requirements.yml } (depending on the specific sub-schema, list is more common for direct file references). Warnings
breaking Ansible Builder 3.x introduced major changes to the execution environment definition file schema. Older `execution-environment.yml` files (schema versions 1 and 2) are not compatible and will likely cause errors or unexpected behavior if not updated to version 3. ↓
fix Update your `execution-environment.yml` file to `version: 3` and adjust its structure according to the Ansible Builder 3.x porting guide, especially sections like `dependencies` and `additional_build_steps`.
deprecated Execution environment schema versions 1 and 2 are deprecated and are scheduled to be removed in Ansible Builder 3.3. Using these older versions will emit warnings and require migration in future releases. ↓
fix Migrate your `execution-environment.yml` files to use `version: 3` as soon as possible to avoid breakage when upgrading Ansible Builder to version 3.3 or later.
gotcha Ansible Builder requires RPM-based container images (e.g., CentOS Stream, Rocky Linux) that use `dnf` or `microdnf`. Non-RPM-based distributions (such as Debian, Ubuntu, or Alpine) are not supported as base images and will fail to build. ↓
fix Ensure your `EE_BASE_IMAGE` (or `base_image.name` in `images` section for v3 schema) in `execution-environment.yml` specifies a compatible RPM-based image.
gotcha Ansible Builder 3.1 significantly changed how Python and system requirements are handled, moving towards strict PEP 508 compliance for Python `requirements.txt`. Non-compliant lines will cause warnings and may lead to unexpected dependency resolution issues, or silent removal if `pip` versions are older. Dependency sanitization is no longer performed by `ansible-builder` itself. ↓
fix Ensure `requirements.txt` files strictly adhere to PEP 508. Upgrade `pip` in your base image if encountering issues with older `pip` versions. Run `ansible-builder` with `-vvv` for detailed output to diagnose dependency parsing problems.
gotcha When using `additional_build_files` with symlinks in an execution environment definition, Ansible Builder 3.2 changed its behavior. Previously, it dereferenced symlinks, copying the target file. Now, it copies the symlink itself. If the symlink's target doesn't exist, this previously resulted in an error, which is now avoided by copying the symlink. ↓
fix Be aware of this behavioral change when relying on symlinks in your build context. Adjust your `additional_build_steps` to handle symlinks explicitly if the previous dereferencing behavior is desired, or ensure targets exist.
Install
sudo dnf install ansible-builder Quickstart
# 1. Create an execution-environment.yml file:
# version: 3
# dependencies:
# galaxy: requirements.yml
# python: requirements.txt
# system: bindep.txt
#
# 2. Create requirements.yml (for Ansible collections):
# collections:
# - community.general
#
# 3. Create requirements.txt (for Python packages):
# ansible-lint
#
# 4. Create bindep.txt (for system-level packages):
# git [platform:rpm]
#
# 5. Build the Execution Environment image:
ansible-builder build --tag my-execution-environment --verbosity 1