Ansible Builder

3.1.1 · active · verified Tue Apr 14

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.

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

pip install ansible-builder Install from PyPI
sudo dnf install ansible-builder Install on RHEL/CentOS Stream (requires AAP repo enabled)

Quickstart

The quickstart involves defining an 'execution-environment.yml' file to specify dependencies (Ansible collections, Python packages, system packages), optional additional build steps, and the base image. Then, use the `ansible-builder build` command to create the container image. Ansible Builder defaults to using Podman as the container runtime, but Docker can be specified with `--container-runtime docker`.

# 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

view raw JSON →