AWX in Action

What Builder Actually Does Under the Hood

When you build an execution environment, ansible-builder generates a multi-stage Dockerfile and runs it through Docker. The build has four stages:

• Stage 1, Base: Builder pulls the base image you declared in images.base_image and copies the build context into it. This is the foundation the later stages build on. Builder does not swap out the base image's Python interpreter; it uses whatever Python the base provides, unless you override it with dependencies.python_interpreter.

• Stage 2, Galaxy: Builder reads requirements.yml and installs the requested Ansible collections using ansible-galaxy collection install. Collections can come from Galaxy, a private Automation Hub, Galaxy NG, a Git URL, or a local tarball, depending on what you declare. The installed collections are staged for the final image.

• Stage 3, Builder: Builder installs Python packages (from requirements.txt or the dependencies.python block) using pip, and resolves system packages using bindep against bindep.txt. System packages are installed with the base image's package manager (dnf, microdnf, apt, apk). Outputs are staged for the final image.

• Stage 4, Final: Builder produces the final image by starting from the base image again and copying in the collections, Python packages, and system packages staged in the previous stages, along with any additional_build_steps you defined. The result is the runnable EE image you push to your registry.

More options and configuration details for the build process are in the Ansible Builder documentation.

You can also customize the final image by adding additional_build_steps to execution-environment.yml. This lets you inject commands at specific points in the build. Common uses:

• Copy files into the image
• Add extra repositories (e.g., EPEL)
• Change the default shell
• Install custom certificates
• Configure a proxy
• Anything else the build needs