DOCSEARCHbyAlgolia
Submit Docs

Ansible Builder

repository·devel·Indexed 43 days ago

https://github.com/ansible/ansible-builder

A tool for automating the creation of Ansible Execution Environments. It leverages collection schemas and user-defined YAML configurations to build consistent, containerized environments using RPM-based images. Features include dependency aggregation for Python and system packages, support for the 3.x definition schema, and an `introspect` command to verify collection metadata.

Tokens
13.4K
Snippets
39
Records
74
Agent score
55%

What's inside Ansible Builder

  1. What is Ansible Builder

    devel
    Ansible Builder is a tool designed to automate the creation of Ansible execution environments. It uses schemas and tooling defined within various Ansible Collections, as well as user-defined configurations, to build consistent container images for running Ansible playbooks.

  2. Top-level sections in Ansible Builder 3.x definition files

    devel

    An Ansible Builder 3.x execution environment definition file is composed of seven top-level sections:

    • additional_build_files: Files to be added to the build context.
    • additional_build_steps: Custom commands for specific build phases.
    • build_arg_defaults: Default build arguments.
    • dependencies: Packages and collections to install.
    • images: Base image configuration.
    • options: Runtime functionality keywords.
    • version: The schema version (must be 3).

  4. Understand Execution Environments

    devel
    An execution environment is a container image designed to serve as an Ansible control node. It packages the Ansible engine along with the specific collections, Python libraries, and system dependencies required to run your automation. Starting with version 2.0, ansible-runner can utilize these images to provide a consistent and isolated runtime for Ansible tasks.

  6. How Ansible Builder execution steps work

    devel

    Ansible Builder operates in two distinct stages:

    1. Creation Stage: Generates a build instruction file (Containerfile for Podman, Dockerfile for Docker) and a build context based on your execution environment definition file. This is performed by the ansible-builder create command.
    2. Build Stage: Runs a containerization tool (Podman or Docker) to build the image using the generated instructions and context. This is performed by the ansible-builder build command, which executes both stages sequentially.

    Use ansible-builder create if you only want to generate the build artifacts (instructions and context) to build the image on a different platform or at a later time.

  7. Understand Python requirements changes in Ansible Builder 3.1

    devel

    In version 3.1, ansible-builder changed how Python and system requirements are handled by simplifying dependency parsing and removing an unmaintained external library.

    Key changes include:

    • PEP 508 Standard: Python requirements files are now expected to follow the PEP 508 standard. While ansible-builder ignores comments (lines starting with #), any non-compliant line will trigger a warning and be passed to pip unmodified. This may expose dependency resolution issues that were previously hidden by the version 3.0 sanitizer.
    • Removal of Dependency Sanitization: ansible-builder no longer combines duplicate dependencies into a single entry. If multiple collections or requirement files list the same dependency, they will now appear as separate entries in the combined requirements file. For example, foo and foo>=1.0 will no longer be merged into foo,foo>=1.0, but will instead appear as two distinct lines.

  8. Configure base images for Execution Environments

    devel

    Ansible Builder requires RPM-based images that use dnf (or compatible) package management.

    Supported/Compatible Base Images:

    • docker.io/redhat/ubi9:latest
    • quay.io/rockylinux/rockylinux:9
    • quay.io/centos/centos:stream9
    • registry.fedoraproject.org/fedora:38
    • registry.redhat.io/ansible-automation-platform-23/ee-minimal-rhel8:latest (requires account)

    Unsupported Images:

    • Non-RPM images such as Debian, Ubuntu, or Alpine are not supported.

  9. Configure additional build files and steps in v3.0

    devel

    Ansible Builder 3.0 provides new ways to inject files and custom commands into the container build process.

    additional_build_files

    Use this section to specify files that should be added to the build context directory. Once added, these files can be referenced or copied by additional_build_steps during any stage of the build.

    additional_build_steps

    You can specify fine-grained build steps or custom commands for any build phase. These commands are inserted directly into the generated Containerfile or Dockerfile. Commands must follow the syntax rules of your container runtime (e.g., Podman or Docker).

    Available build step hooks:

    • prepend_base / append_base
    • prepend_galaxy / append_galaxy
    • prepend_builder / append_builder
    • prepend_final / append_final

  10. Understand the Control Node concept

    devel
    A Control node is the machine or container where Ansible is actually executed. It is the environment that initiates connections to managed nodes and runs playbooks. In the context of ansible-builder, the execution environment you build becomes the containerized control node.

  11. Bindep parse error detection in version 3.2

    devel

    Ansible Builder 3.2 now provides improved error detection for bindep.txt files. If the bindep program encounters unparsable content and exits with code 2, the build process will now fail immediately with the message Error: bindep.txt contains unparsable content and exit with code 2.

    Requirement: Your container image must have bindep version 2.14.0 or higher installed for this immediate failure behavior to work. Versions below 2.14.0 will not halt execution on unparsable content.

  12. Understand the Ansible Builder 3.x definition schema

    devel

    The Ansible Builder 3.x execution environment definition file is composed of seven top-level sections:

    • additional_build_files: Files to be added to the build context.
    • additional_build_steps: Custom build instructions (prepend/append) for different stages of the build.
    • build_arg_defaults: Default values for build arguments.
    • dependencies: Definitions for Ansible core, runner, galaxy collections, python packages, and system packages.
    • images: Configuration for the base image used in the build.
    • options: Additional builder configuration options.
    • version: The schema version (must be set to 3 for version 3 features).