Developing Advanced Automation with Red Hat Ansible Automation Platform
Build a custom automation execution environment image by using the
ansible-buildercommand.
Red Hat provides several Ansible automation execution environments that suit the needs of many users. These automation execution environments include the most common Ansible Content Collections.
You can use the ansible-navigator images command to inspect a container image and view the collections, Python packages, and operating system packages it includes.
Image: ee-supported-rhel8:latest Description 0│Image information Information collected from image inspection 1│General information OS and python version information 2│Ansible version and collections Information about ansible and ansible collect 3│Python packages Information about python and python packages 4│Operating system packages Information about operating system packages 5│Everything All image information
The automation execution environments that Red Hat provides might be sufficient for your playbooks. In that case, you do not need to create new automation execution environments.
Sometimes, you might need an Ansible Content Collection that is not included in one of the existing automation execution environments. Often, you can install these extra collections in your Ansible project and then use an existing automation execution environment without having to build a new one.
On the other hand, you should consider creating a custom automation execution environment in the following situations:
You frequently reuse specific collections that are not included in the existing automation execution environments. It is more efficient to embed those collections in a custom automation execution environment than to install them from the project
requirements.ymlfile every time you run a playbook in that project. This is especially true if you have many projects that use that collection.The collection you want to use requires Python packages or software that are not included in an existing automation execution environment.
You need to use a collection that conflicts with another collection in your existing automation execution environments.
You use the ansible-builder command to create the container images used for automation execution environments.
The ansible-builder RPM package provides that command.
[root@host ~]# yum install ansible-builderCreate a working directory to prepare the files that you need to build the automation execution environment container image.
The ansible-builder command searches this working directory for its execution-environment.yml configuration file, which it uses to determine how to build the container image.
The following is an example execution-environment.yml file:
--- version: 1 build_arg_defaults: EE_BASE_IMAGE: registry.redhat.io/ansible-automation-platform-22/ee-minimal-rhel8:latestEE_BUILDER_IMAGE: registry.redhat.io/ansible-automation-platform-22/ansible-builder-rhel8:latest
ansible_config: ansible.cfg
dependencies: galaxy: requirements.yml
python: requirements.txt
system: bindep.txt
| The NoteYou are not allowed to publicly distribute container images that you build on top of the automation execution environment images that Red Hat provides with Red Hat Ansible Automation Platform. To distribute your images on a public platform, such as Quay.io, use the public Red Hat only supports container images that you build on top of the Red Hat images. |
| The optional |
| The optional |
| The |
| The |
| The |
In the requirements.yml file, list the content collections that ansible-builder should install inside the automation execution environment.
The following example is a straightforward requirements.yml file that instructs the ansible-builder command to install the community.aws and community.general collections from Ansible Galaxy.
--- collections: - community.aws - community.general
The following example is a more complex requirements.yml file.
--- collections: - name: redhat.insights
| The name of the collection. |
| A specific version of the collection.
If not specified, then the |
| The distribution platform that provides the collection.
This example uses the Ansible automation hub address.
You must create an |
| A collection from private automation hub.
You also need to provide your token in an |
The following example ansible.cfg file provides the parameters that the ansible-builder command needs to authenticate to Ansible automation hub and to private automation hub (at hub.example.com in this example).
[galaxy] server_list = ansible_automation_hub, my_hub, galaxy [galaxy_server.ansible_automation_hub] url=https://console.redhat.com/api/automation-hub/ auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token token=eyJh...0Nwk [galaxy_server.my_hub] url=https://hub.example.com/api/galaxy/content/rh-certified/ token=e8e4...b0c2 [galaxy_server.galaxy] url=https://galaxy.ansible.com/
In the requirements.txt file, list the Python packages that ansible-builder must install inside the automation execution environment.
The following example requirements.txt file lists some required Python packages.
For each package, you can provide a specific version to select.
sh==1.13.1 jsonschema>=3.2.0,<4.0.1 textfsm ttp xmltodict dnspython
Some collections include a requirements.txt file.
In that case, you do not have to duplicate that file in your requirements.txt file.
In the bindep.txt file, list the RPM packages that ansible-builder must install inside the automation execution environment.
The following bindep.txt file lists the RPM packages required by the preceding examples.
rsync [platform:rpm] kubernetes-client [platform:rpm]
The bindep tool, which processes the bindep.txt file, can manage packages for several Linux distributions.
Different distributions might have other package names for the same software.
In the preceding file, the [platform:rpm] directive targets all the Linux distributions that use the RPM packaging system.
Some collections include a bindep.txt file.
In that case, you do not have to duplicate that file in your bindep.txt file.
If the system on which you run the build process has a valid subscription, then the ansible-builder command has access to the same RPM packages as that system.
However, if you do not register your system with Red Hat, then the build process has only access to the Red Hat Universal Base Images (UBI) repositories.
These repositories are publicly available but only provide a limited set of RPM packages.
The packages you define in the bindep.txt file might not be available in these repositories.
The execution environment builder automatically pulls the base and the builder images if they are not already available locally. If you use images from a container registry that requires authentication, then you must authenticate before starting the build process.
The following example shows how to log in to the Red Hat container registry that hosts the default images, ee-minimal-rhel8 and ansible-builder-rhel8:
[user@host demo]$ podman login registry.redhat.ioAfter you have prepared your configuration files and authenticated to the container registry, use the ansible-builder build command to create your automation execution environment container image.
Use the --tag (or -t) option to provide a name for the container image.
The name has two parts: a name and an optional tag.
For example, use the --tag demo:v1.0 option to name the container demo and give it the v1.0 tag.
The tag defaults to latest if you do not specify it.
For example, using the --tag demo option is the equivalent of using --tag demo:latest.
A successful build creates a new container image.
[user@host demo]$ ansible-builder build --tag ee-demo:v1.0
Running command:
podman build -f context/Containerfile -t ee-demo:v1.0 context
Complete! The build context can be found at: /home/user/demo/contextUse the podman images command to display local container images.
[user@host demo]$ podman images
REPOSITORY TAG IMAGE ID CREATED SIZE
localhost/ee-demo v1.0 9e1e281437a2 2 hours ago 744 MB
...output omitted...For more advanced configurations, you might have to customize the build process. For example, suppose your private automation hub uses a TLS certificate signed by a corporate certificate authority (CA). In that case, you must provide that CA certificate to the build process so that it can download collections from the distribution platform.
The execution environment builder operates in two stages:
The command creates the
context/directory in the current directory. In that directory, it creates theContainerfilefile, the equivalent of aDockerfilefile, which contains instructions for thepodman buildcommand. It also creates an_build/subdirectory and then copies yourrequirements.yml,ansible.cfg,requirements.txt, andbindep.txtfiles into it so that the build process can access them.The command then runs the
podman buildcommand, which constructs the resulting automation execution environment container image.
To prepare for customizing the build process, use the ansible-builder create command to perform the first stage:
[user@host demo]$lsansible.cfg bindep.txt execution-environment.yml requirements.txt requirements.yml [user@host demo]$ansible-builder createComplete! The build context can be found at: /home/user/demo/context [user@host demo]$tree. ├── ansible.cfg ├── bindep.txt ├──context│├── _build││ ├── ansible.cfg││ ├── bindep.txt││ ├── requirements.txt││ └── requirements.yml│└── Containerfile├── execution-environment.yml ├── requirements.txt └── requirements.yml 2 directories, 10 files
Important
The ansible-builder create command always overwrites the context/Containerfile file.
Any changes you make to the context/Containerfile file are lost.
Default values for build arguments can be specified in the execution-environment.yml configuration file, defining the build_arg_defaults variable as a dictionary of arguments and their values.
You can also specify these settings from the ansible-builder command line with the --build-arg option.
If you also have an execution-environment.yml file, the values specified by the --build-arg option always take precedence.
Build arguments that are used by ansible-builder include:
ANSIBLE_GALAXY_CLI_COLLECTION_OPTSpasses additional command-line options to theansible-galaxycommand that the build process runs. For example, you can add the--preoption if you want to install prerelease versions of collections.EE_BASE_IMAGEspecifies the parent image for the execution environment.EE_BUILDER_IMAGEspecifies the image used for compiling tasks.
build_arg_defaults: EE_BASE_IMAGE: registry.redhat.io/ansible-automation-platform-22/ee-minimal-rhel8:latest EE_BUILDER_IMAGE: registry.redhat.io/ansible-automation-platform-22/ansible-builder-rhel8:latest
The current build arguments are hard coded into the Containerfile file when you use the ansible-builder create command to generate that file.
After running the ansible-builder create command, you can navigate to the context/ directory and modify the Containerfile file to adapt it to your needs.
For example, you could add the following two directives in the Containerfile file to inject a private CA's certificate into the image:
ARG EE_BASE_IMAGE=registry.redhat.io/ansible-automation-platform-22/ee-minimal-rhel8:latest ARG EE_BUILDER_IMAGE=registry.redhat.io/ansible-automation-platform-22/ansible-builder-rhel8:latest FROM $EE_BASE_IMAGE as galaxy ARG ANSIBLE_GALAXY_CLI_COLLECTION_OPTS= USER rootCOPY my-company-ca.pem /etc/pki/ca-trust/source/anchorsRUN update-ca-trustADD _build/ansible.cfg ~/.ansible.cfg ...output omitted...
For this example, you would place the my-company-ca.pem certificate file in the context/ directory.
When ready to build the container image, you manually execute the second stage by running the podman build command.
[user@host demo]$podman build -f context/Containerfile -t ee-demo:v2.0 contextSTEP 1: FROM registry.redhat.io/ansible-automation-platform-22/ee-minimal-rhel8:latest AS galaxy STEP 2: ARG ANSIBLE_GALAXY_CLI_COLLECTION_OPTS= --> 5894c40a543 STEP 3: USER root --> 913568f77bbSTEP 4: COPY my-company-ca.pem /etc/pki/ca-trust/source/anchors--> b9c4d7eaad0STEP 5: RUN update-ca-trust--> be65558ebb8 STEP 6: ADD _build/ansible.cfg ~/.ansible.cfg --> 4a5410ba1c2 ...output omitted... STEP 22: COMMIT ee-demo:v2.0 --> 8be47093daa 8be47093daaae18160468f3db6e0335d55d0d11c838c7e285d74037e4a31d8a9 [user@host demo]$podman imagesREPOSITORY TAG IMAGE ID CREATED SIZE localhost/ee-demo v2.0 ba77b0d0a59d 2 minutes ago 308 MB ...output omitted...
References
Knowledgebase: What’s new with Ansible Automation Platform 2.0: Developing with ansible-builder and Automation execution environments. Knowledgebase: Universal Base Images (UBI): Images, Repositories, Packages, and Source Code
The Anatomy of Automation Execution Environments
Introduction to Ansible Builder
For more information, refer to the Using Ansible Builder chapter in the Ansible Builder Guide at https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/2.1/html-single/ansible_builder_guide/index#assembly-using-builder
