As of version 2.0, Ansible AWX/Ansible Automation Platform has replaced Python virtual environments with Execution Environments(EEs). In a nutshell, it’s running all of your automations inside of containers. Execution Environments are container images that serve as Ansible control nodes. Starting in version 2.0, ansible-runner can make use of these images. An Ansible AWX/Ansible Automation Platform Execution environment(EE) is a container image used to execute Ansible playbooks and roles. It provides a defined, consistent, portable environment for executing automation.
Automation execution environments provide a standard way to build and distribute the environment that automation runs in, which reduces complexity and makes it faster and simpler to develop and deploy automation.
My assumption at this stage is that you already have Ansible AWX/Ansible Automation Platform 2 already installed and youre now ready to create a custome Execution environment.
An Execution Environment contains the folllowing components
- Ansible Runner
- Ansible Galaxy Collections
- Python and/or system dependencies of: modules/plugins in collections, content in ansible-base & custom user needs
For us to be able to build the images, we need to install docker or podman as well as ansible-builder Python package.
Install from PyPi
$ pip install ansible-builder Requirement already satisfied: ansible-builder in ./.local/lib/python3.9/site-packages (3.0.0) Requirement already satisfied: PyYAML in ./.local/lib/python3.9/site-packages (from ansible-builder) (6.0.1) Requirement already satisfied: requirements-parser in ./.local/lib/python3.9/site-packages (from ansible-builder) (0.5.0) Requirement already satisfied: bindep in ./.local/lib/python3.9/site-packages (from ansible-builder) (2.11.0) Requirement already satisfied: jsonschema in ./.local/lib/python3.9/site-packages (from ansible-builder) (4.18.4) Requirement already satisfied: Parsley in ./.local/lib/python3.9/site-packages (from bindep->ansible-builder) (1.3) Requirement already satisfied: pbr>=2.0.0 in ./.local/lib/python3.9/site-packages (from bindep->ansible-builder) (5.11.1) Requirement already satisfied: distro>=1.7.0 in ./.local/lib/python3.9/site-packages (from bindep->ansible-builder) (1.8.0) Requirement already satisfied: packaging in ./.local/lib/python3.9/site-packages (from bindep->ansible-builder) (23.1) Requirement already satisfied: attrs>=22.2.0 in ./.local/lib/python3.9/site-packages (from jsonschema->ansible-builder) (23.1.0) Requirement already satisfied: jsonschema-specifications>=2023.03.6 in ./.local/lib/python3.9/site-packages (from jsonschema->ansible-builder) (2023.6.1) Requirement already satisfied: referencing>=0.28.4 in ./.local/lib/python3.9/site-packages (from jsonschema->ansible-builder) (0.29.3) Requirement already satisfied: rpds-py>=0.7.1 in ./.local/lib/python3.9/site-packages (from jsonschema->ansible-builder) (0.8.11) Requirement already satisfied: types-setuptools>=57.0.0 in ./.local/lib/python3.9/site-packages (from requirements-parser->ansible-builder) (18.104.22.168)
Install from the source code
This is the mainline development branch from GitHub.
$ pip install https://github.com/ansible/ansible-builder/archive/devel.zip Defaulting to user installation because normal site-packages is not writeable Collecting https://github.com/ansible/ansible-builder/archive/devel.zip Downloading https://github.com/ansible/ansible-builder/archive/devel.zip | 145.2 kB 701.2 kB/s 0:00:00 Installing build dependencies ... done Getting requirements to build wheel ... done Installing backend dependencies ... done Preparing metadata (pyproject.toml) ... done .... Successfully built ansible-builder Installing collected packages: ansible-builder Attempting uninstall: ansible-builder Found existing installation: ansible-builder 3.0.0 Uninstalling ansible-builder-3.0.0: Successfully uninstalled ansible-builder-3.0.0 Successfully installed ansible-builder-3.0.1.dev26+gce52b2a9
Build Custom Execution Environment
In your home directory, create a directory and name it my-builder-env. This directory is to contain all the required files to build our image.
The ansible-builder shall help us build container images with the definition file execution-environment.yml. A typical execution-environment.yml contains the base container image (EE_BASE_IMAGE), ansible.cfg, and other dependency file details.
With your favorite text editor, create execution-environment.yml file with the following contents:
--- version: 3 build_arg_defaults: ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: '--pre' dependencies: ansible_core: package_pip: ansible-core==2.15 ansible_runner: package_pip: ansible-runner galaxy: requirements.yml python: requirements.txt system: bindep.txt images: base_image: name: quay.io/ansible/awx-ee:latest additional_build_files: - src: ansible.cfg dest: configs additional_build_steps: prepend_galaxy: - ADD _build/configs/ansible.cfg ~/.ansible.cfg prepend_final: | RUN whoami RUN cat /etc/os-release append_final: - RUN echo This is a post-install command! - RUN ls -la /etc
In the same directory, create ansible.cfg with the following contant:
[galaxy] server_list = galaxy [galaxy_server.galaxy] url=https://galaxy.ansible.com/
collections: - community.general - community.crypto - ansible.posix - awx.awx - ansible.posix - ansible.utils - community.network
bindep.txt requirements.txt can remain empty unless we have extra dependencies to add.
The file system tree:
# tree . ├── ansible.cfg ├── bindep.txt ├── execution-environment.yml ├── requirements.txt └── requirements.yml
Build the Image
ansible-builder buildcommand takes an execution environment definition as an input. It outputs the build context necessary for building an execution environment image, and it builds that image. The image can be re-built with the build context elsewhere, and give the same result. By default, it looks for a file named
execution-environment.yml in the current directory.
Using the configuration files, we can now build the EE image using the command below.
$ ansible-builder build --tag technnix-awx-ee:v1.0 --verbosity 2 Running command: podman build -f context/Containerfile -t technnix-awx-ee:v1.0 context Complete! The build context can be found at: /home/technnix/my-builder-env/context
THe current file system structure:
tree . ├── ansible.cfg ├── ansible-navigator.log ├── bindep.txt ├── context │ ├── _build │ │ ├── bindep.txt │ │ ├── configs │ │ │ └── ansible.cfg │ │ ├── requirements.txt │ │ ├── requirements.yml │ │ └── scripts │ │ ├── assemble │ │ ├── check_ansible │ │ ├── check_galaxy │ │ ├── entrypoint │ │ ├── install-from-bindep │ │ └── introspect.py │ └── Containerfile ├── execution-environment.yml ├── requirements.txt └── requirements.yml 4 directories, 17 files
List the images using podman command:
$ podman image list REPOSITORY TAG IMAGE ID CREATED SIZE localhost/technnix-awx-ee v1.0 eebe0b77209d 5 minutes ago 1.65 GB quay.io/ansible/awx-ee latest fbdf4a114ccb 8 hours ago 1.51 GB
We have now successfully built the EE image(
localhost/technnix-awx-ee ). To use it, we need to push it to an image registry so that our Ansible AWX/Ansible Automation Platform can pull it from there and use it to run jobs.