Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

How to create execution environments using ansible-builder

May 8, 2023
Tathagata Paul
Related topics:
Automation and managementContainersPython
Related products:
Red Hat Ansible Automation Platform

Share:

    The execution environment builder (aka Ansible Builder) is a part of Red Hat Ansible Automation Platform. It is a command-line interface (CLI) tool for building and creating custom execution environments. The Ansible Builder project enables users to automate and accelerate the process of creating execution environments. This article will show you how to install and use the execution environment builder CLI tool.

    Installing the execution environment builder

    The execution environment builder makes it easier for Ansible Automation Platform content creators and administrators to build custom execution environments. They can use dependency information from various Ansible Content Collections and directly from the user.

    Step 1: Install the execution environment builder tool

    Install the execution environment builder tool from the Python Package Index (PyPI) by using the following command:

    pip install ansible-builder

    Step 2: Access the ansible-builder subcommands

    To access the subcommands of ansible-builder, run build and create commands to get help output.

    The build subcommand will build the execution environment using the definition file.

    ansible-builder build –help

    It populates the build context and then uses Podman or Docker to create the execution environment image. The help output appears as follows:

    usage: ansible-builder build [-h] [-t TAG] [--container-runtime {podman,docker}] [--build-arg BUILD_ARGS] [-f FILENAME] [-c BUILD_CONTEXT]
                                 [--output-filename {Containerfile,Dockerfile}] [-v {0,1,2,3}]
    
    Creates a build context (including a Containerfile) from an execution environment spec. The build context will be populated from the execution environment spec. After that, the specified container runtime podman/docker will be invoked to build an image from that definition. After building the image, it can be used locally or published using the
    supplied tag.
    
    optional arguments:
      -h, --help            show this help message and exit
      -t TAG, --tag TAG     The name for the container image being built (default: ansible-execution-env:latest)
      --container-runtime {podman,docker}
                            Specifies which container runtime to use (default: podman)
      --build-arg BUILD_ARGS
                            Build-time variables to pass to any podman or docker calls. Internally ansible-builder makes use of ANSIBLE_GALAXY_CLI_COLLECTION_OPTS, EE_BASE_IMAGE,
                            EE_BUILDER_IMAGE.
      -f FILENAME, --file FILENAME
                            The definition of the execution environment (default: execution-environment.yml)
      -c BUILD_CONTEXT, --context BUILD_CONTEXT
                            The directory to use for the build context (default: context)
      --output-filename {Containerfile,Dockerfile}
                            Name of file to write image definition to (default depends on --container-runtime, Containerfile for podman and Dockerfile for docker)
      -v {0,1,2,3}, --verbosity {0,1,2,3}
                            Increase the output verbosity, for up to three levels of verbosity (invoked via "--verbosity" or "-v" followed by an integer ranging in value from 0 to
                            3) (default: 2)
    

    The create subcommand works similar to the build command.

    ansible-builder create –help

    However, it will not build the execution environment image as you will see in the following output:

    usage: ansible-builder build [-h] [-t TAG] [--container-runtime {podman,docker}] [--build-arg BUILD_ARGS] [-f FILENAME] [-c BUILD_CONTEXT]
                                 [--output-filename {Containerfile,Dockerfile}] [-v {0,1,2,3}]
    
    Creates a build context (including a Containerfile) from an execution environment spec. The build context will be populated from the execution environment spec. After that,
    the specified container runtime podman/docker will be invoked to build an image from that definition. After building the image, it can be used locally or published using the
    supplied tag.
    
    optional arguments:
      -h, --help            show this help message and exit
      -t TAG, --tag TAG     The name for the container image being built (default: ansible-execution-env:latest)
      --container-runtime {podman,docker}
                            Specifies which container runtime to use (default: podman)
      --build-arg BUILD_ARGS
                            Build-time variables to pass to any podman or docker calls. Internally ansible-builder makes use of ANSIBLE_GALAXY_CLI_COLLECTION_OPTS, EE_BASE_IMAGE,
                            EE_BUILDER_IMAGE.
      -f FILENAME, --file FILENAME
                            The definition of the execution environment (default: execution-environment.yml)
      -c BUILD_CONTEXT, --context BUILD_CONTEXT
                            The directory to use for the build context (default: context)
      --output-filename {Containerfile,Dockerfile}
                            Name of file to write image definition to (default depends on --container-runtime, Containerfile for podman and Dockerfile for docker)
      -v {0,1,2,3}, --verbosity {0,1,2,3}
                            Increase the output verbosity, for up to three levels of verbosity (invoked via "--verbosity" or "-v" followed by an integer ranging in value from 0 to
                            3) (default: 2)
    

    Step 3: Populate the ansible-builder spec

    Populate the ansible-builder spec to build the custom execution environment by running the following command:

    mkdir project_directory && cd project_directory

    Populate the execution-environment.yml file:

    cat <<EOT >> execution-environment.yml
    ---
    version: 1
    dependencies:
      galaxy: requirements.yml
    EOT
    
    

    Create a requirements.yml file and populate the contents with the following:

    cat <<EOT >> requirements.yml
    ---
    collections:
      - name: servicenow.itsm
    EOT

    Through the spec and requirements file, we ensure that execution environment builder will download the servicenow.itsm collection while building the execution environment. The default download location is galaxy.ansible.com. You can also point to an automation hub or your own hub instance in the spec file.

    Step 4: Build the execution environment

    Build the execution environment using the previously created files. Run the following command to create a new custom execution environment called custom-ee:

    ansible-builder build -v3 -t custom-ee

    The -v3 flag adds verbosity to the CLI run, and -t custom-ee will tag your image with the name you provided.

    The output appears as follows:

    Ansible Builder is building your execution environment image, "custom-ee".
    File context/_build/requirements.yml will be created.
    Rewriting Containerfile to capture collection requirements
    Running command:
      podman build -f context/Containerfile -t custom-ee context
    [1/3] STEP 1/7: FROM registry.redhat.io/ansible-automation-platform-21/ee-minimal-rhel8:latest AS galaxy
    [1/3] STEP 2/7: ARG ANSIBLE_GALAXY_CLI_COLLECTION_OPTS=
    --> 88d9ea223d0
    [1/3] STEP 3/7: USER root
    --> 549f29055c2
    [1/3] STEP 4/7: ADD _build /build
    --> 0d3e9515b12
    [1/3] STEP 5/7: WORKDIR /build
    --> 3b290acf78c
    [1/3] STEP 6/7: RUN ansible-galaxy role install -r requirements.yml --roles-path /usr/share/ansible/roles
    Skipping install, no requirements found
    --> 8af36370e78
    [1/3] STEP 7/7: RUN ansible-galaxy collection install $ANSIBLE_GALAXY_CLI_COLLECTION_OPTS -r requirements.yml --collections-path /usr/share/ansible/collections
    Starting galaxy collection install process
    Process install dependency map
    …
    
    

    Run the following commands to check the image list:

    podman images

    The output appears as follows:

    REPOSITORY                                                   TAG         IMAGE ID           CREATED                SIZE
    localhost/custom-ee                                        latest      bfe6c40bad52    21 seconds ago      626 MB
    

    Step 5: Build a complex execution environment

    To build a complex execution environment, go back into the project directory with the following command:

    cd project_directory

    Edit the execution-environment.yml file and add the following content:

    cat <<EOT >> execution-environment.yml
    ---
    version: 1
    dependencies:
      galaxy: requirements.yml
      python: requirements.txt
      system: bindep.txt
    additional_build_steps:
      prepend: |
        RUN whoami
        RUN cat /etc/os-release
      append:
        - RUN echo This is a post-install command!
        - RUN ls -la /etc
    EOT

    We can see the following:

    • Python requirements were added through the requirements.txt file, which will hold the pip dependencies.
    • We added a bindep.txt, which will hold the rpm installs.
    • Additional build steps that will run before (prepend) and after (append) the build steps.

    Now create a new file called requirements.yml and append the following content:

    cat <<EOT >> requirements.yml
    ---
    
    collections:
    
      - name: servicenow.itsm
      - name: ansible.utils
    EOT

    We added a new collection called ansible.utils alongside the servicenow.itsm file.

    Create a new file called requirements.txt and then append the following:

    cat <<EOT >> requirements.txt
    gcp-cli
    ncclient
    netaddr
    paramiko
    EOT

    This contains the Python requirements that need to be installed via pip.

    Create a new file called bindep.txt and then append the following:

    cat <<EOT >> bindep.txt
    findutils [compile platform:centos-8 platform:rhel-8]
    gcc [compile platform:centos-8 platform:rhel-8]
    make [compile platform:centos-8 platform:rhel-8]
    python38-devel [compile platform:centos-8 platform:rhel-8]
    python38-cffi [platform:centos-8 platform:rhel-8]
    python38-cryptography [platform:centos-8 platform:rhel-8]
    python38-pycparser [platform:centos-8 platform:rhel-8]
    EOT

    This file contains the rpm requirements needed to be installed using dnf.

    Run the following build:

    ansible-builder build -v3 -t custom-ee

    The output is as follows:

    Ansible Builder is building your execution environment image, "custom-ee".
    File context/_build/requirements.yml will be created.
    File context/_build/requirements.txt will be created.
    File context/_build/bindep.txt will be created.
    Rewriting Containerfile to capture collection requirements
    Running command:
      podman build -f context/Containerfile -t custom-ee context
    [1/3] STEP 1/7: FROM registry.redhat.io/ansible-automation-platform-21/ee-minimal-rhel8:latest AS galaxy
    [1/3] STEP 2/7: ARG ANSIBLE_GALAXY_CLI_COLLECTION_OPTS=
    --> Using cache 88d9ea223d01bec0d53eb7efcf0e76b5f7da0285a411f2ce0116fe9641cbc3a0
    --> 88d9ea223d0
    [1/3] STEP 3/7: USER root
    --> Using cache 549f29055c2f1ba0ef3f7c5dfdc67a40302ff0330af927adb94fbcd7b0b1e7b4
    --> 549f29055c2
    [1/3] STEP 4/7: ADD _build /build
    --> 6b9ee91e773
    [1/3] STEP 5/7: WORKDIR /build
    --> 5518e019f2d
    [1/3] STEP 6/7: RUN ansible-galaxy role install -r requirements.yml --roles-path /usr/share/ansible/roles
    Skipping install, no requirements found
    --> 60c1605d66c
    [1/3] STEP 7/7: RUN ansible-galaxy collection install $ANSIBLE_GALAXY_CLI_COLLECTION_OPTS -r requirements.yml --collections-path /usr/share/ansible/collections
    Starting galaxy collection install process
    Process install dependency map

    You can check the context or Containerfile to see all the steps you took to build the execution environment. You can transfer the context directory to a different server and replicate the image creation via docker or podman commands.

    Pushing the execution environment to a private automation hub

    Log in to the private automation hub by using the podman command:

    podman login <automation hub url>

    Then tag the image before pushing it to the hub as follows:

    podman tag localhost/custom-ee <automation hub url>/developers-bu-aap-builder

    Finally, push it to the private automation hub as follows:

    podman push <automation hub url>/developers-bu-aap-builder

    We can see the image pushed to the private automation hub in Figure 1:

    The private automation hub page showing multiple pushed execution environment images.
    Figure 1: The private automation hub page showing multiple pushed execution environment images.

    Continue your automation journey with Ansible Automation Platform

    Get started with Ansible Automation Platform by exploring interactive labs. Check out Red Hat’s hands-on labs for all skill levels to learn more. The wide range of labs include useful Linux commands, Install software using package managers, and Deploying containers using container tools [podman]. Try these labs to see your favorite products in action. Ansible Automation Platform is also available as a managed offering on Microsoft Azure and as a self-managed offering on AWS.

    Last updated: May 30, 2025

    Related Posts

    • Ansible and automation: The best of 2021

    • Best practices for building images that pass Red Hat Container Certification

    • Build your first application using Python 3.5 on RHEL 7 with containers and Red Hat Software Collections

    • Four reasons developers should use Ansible

    • What’s new in Ansible Automation Platform 2.2

    Recent Posts

    • How Kafka improves agentic AI

    • How to use service mesh to improve AI model security

    • How to run AI models in cloud development environments

    • How Trilio secures OpenShift virtual machines and containers

    • How to implement observability with Node.js and Llama Stack

    What’s up next?

    Download the Red Hat Certified Engineer (RHCE) Ansible Automation Study Guide and learn to build and operate scalable IT automation across cloud, hybrid, and edge environments.

    Get the e-book
    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform
    • See all products
    • See all technologies

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue