This is a quick guide on creating a custom execution environment for managing network devices on AAP 2.x.
Table of Contents
In this repo you will find four documents.
A custom execution environment (EE) is needed when the default environments don't provide the necessary collections and their dependencies your projects require. There are three types of dependencies handled by EEs: collections, Python libraries, and host packages.
The dependency files can be named however you want, but they need to follow the syntax the build system uses. Ansible Galaxy dependencies are specified in the standard requirements.yml format, Python in Pip compatible format, and system packages in the bindep format.
Depending on the collections you are using, specifying Python and system dependencies manually may not be necessary. For example, the
cisco.ios collection provides its own
bindep.txt files that the
ansible-builder tool will use in resolving the necessary dependencies. If a collection doesn't provide these file itself, or you need other dependencies outside the scope of the collections you will need to specify them yourself.
In this repository all of the collections follow best practice and describe the dependencies they need, so the inclusion of
system.txt is purely academic.
With the dependencies set, the execution environment needs to be configured. The two main sections are the
For the build arguments, its recommended to specify the Base (runtime) and Builder (creation) images to use when generating your execution environment. As we are deploying on AAP we will use the Red Hat supported AAP 2.1 base and builder images that use Ansible 2.12. These images are based on UBI 8 and as such can be used without a Red Hat subscription. However, it is possible that a host package dependency may not be included in the UBI repositories, hence the recommendation to run the builder on an entitled system. This is the case for this project, which will try to pull in
libssh-devel which is only avaialble in the full RHEL repositories.
build_arg_defaults: EE_BASE_IMAGE: "registry.redhat.io/ansible-automation-platform-21/ee-minimal-rhel8:latest" EE_BUILDER_IMAGE: "registry.redhat.io/ansible-automation-platform-21/ansible-builder-rhel8:latest"
In order to use the Red Hat images, authenticate to the Red Hat registry using a service account, such as the one created for AAP.
$ podman login registry.redhat.io Username: <ServiceAccountName> Password: <ServiceAccountPassword>
The dependencies section is straightfoward, just mapping which files to use for the given dependency type:
dependencies: galaxy: galaxy.yml python: python.txt system: system.txt
There are other sections that are available for use but aren't needed in the context of this demo. They can be reviewed in the Execution Environment Setup Reference.
With the base configuration done, all that's left to do is build the EE image. As I'm using the registry repository of
quay.io/omenos/aap-ee, I'll specify the custom tag name to use when building and maximize the verbosity of the output:
$ ansible-builder build -v 3 --tag quay.io/omenos/aap-ee:21-networking-ee ... build output ... $ podman images quay.io/omenos/aap-ee:21-networking-ee REPOSITORY TAG IMAGE ID CREATED SIZE quay.io/omenos/aap-ee 21-networking-ee 5157588846f5 10 seconds ago 482 MB
With the image built, we can now push the image to the registry.
$ podman push quay.io/omenos/aap-ee:21-networking-ee ...pushing to registry...
Now in the AAP web view, navigate to Administration > Execution Environments and click "Add". Fill in the options with the appropriate details and hit "Save". Some notes:
-v2, etc) then it may be best to choose "Only pull the image if not present before running". If you plan on using transient tags (
:latest), it may be best to always pull the image before a run to ensure you have the desired image.
The EE will now be available for use when creating/modifying job templates and projects. The EE can also be defined as the default runtime for an entire project so all job templates will inherit that preference.