{"id":5846,"library":"ansible-builder","title":"Ansible Builder","description":"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.","status":"active","version":"3.1.1","language":"en","source_language":"en","source_url":"https://github.com/ansible/ansible-builder","tags":["ansible","automation","container","execution environment","build","devops"],"install":[{"cmd":"pip install ansible-builder","lang":"bash","label":"Install from PyPI"},{"cmd":"sudo dnf install ansible-builder","lang":"bash","label":"Install on RHEL/CentOS Stream (requires AAP repo enabled)"}],"dependencies":[{"reason":"Containerization tool for building images (default)","package":"podman","optional":false},{"reason":"Alternative containerization tool for building images","package":"docker","optional":true}],"imports":[],"quickstart":{"code":"# 1. Create an execution-environment.yml file:\n# version: 3\n# dependencies:\n#   galaxy: requirements.yml\n#   python: requirements.txt\n#   system: bindep.txt\n#\n# 2. Create requirements.yml (for Ansible collections):\n# collections:\n#   - community.general\n#\n# 3. Create requirements.txt (for Python packages):\n# ansible-lint\n#\n# 4. Create bindep.txt (for system-level packages):\n# git [platform:rpm]\n#\n# 5. Build the Execution Environment image:\nansible-builder build --tag my-execution-environment --verbosity 1","lang":"bash","description":"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`."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<3.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.2.0"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}