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-builderNo compatibility data collected yet for this library.
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`.
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`.
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.
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.
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.
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.
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.
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.
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.
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.
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).