👋 Introduction

On the VS Code tab on the left side you will see that we have a tab called "file." Click File→Open folder and select the directory opened called minimal-downstream-from-galaxy and this directory has a file called execution-environment.yml.

This file is our execution environment definition file, and the default name for this file is execution-environment.yml. By default we mean that if we just run the build subcommand of ansible-builder in this directory, ansible-builder will understand that it needs to look at this file for the definition of the execution environment it needs to create.

You can also create any file name you want, but if you change the file name you will have to inform ansible-builder which file to pick the definition from. Information on this is available in the ansible-builder build --help command. Here’s an example of a different definition file name:

Suppose we create the definition file as ee-definition.yml, then we can run the following command to build the execution environment:

The above command will not do anything in this lab, and if you run it you’ll see an error saying that ee-definition.yml is not found. For this lab, we will stick to the default name execution-environment.yml for the definition file.

As we mentioned that we are using ansible-builder version 3.0.0 for this lab, this also means that to take advantage of features provided with this version you need to add an identifier in the definition file. If you don’t do this, ansible-builder v3 will fail to understand the schema of the definition and some keys that are newly introduced, resulting in failures.

For this task, just add the following line to the execution-environment.yml:

Execution environments are container images acting as Ansible environments. An important aspect for the definition file is to define a base image that the builder will use to build an EE. Think of this step as the starting point for your execution environment, and then we keep adding things on top.

Add this to the execution-environment.yml after the version line:

Now you might be asking yourself what image this refers to. The answer: this is the minimal execution environment supplied with AAP 2.4, which is the latest release of Ansible Automation Platform. Another image that comes with the platform is the supported execution environment, which also has the Ansible supported collections baked on top of the minimal execution environment.

For the purpose of this lab, as we are showing how to build an execution environment, we are starting from the minimal execution environment as the base image for our EE.

Next step is to add the collection that we want to include in our execution environment. For this challenge, as we are adding the ansible.netcommon collection from the default Galaxy, we don’t need to add an ansible.cfg to point to the Automation Hub used in this lab.

A simple collection definition for EE looks like this — add this to the execution-environment.yml file after the images section:

The above section specifies that we need to bake the ansible.netcommon collection into the execution environment. There are different dependencies you can specify for your execution environment in this section, like python and system dependencies, based on your automation needs.

One advantage of builder v3 is that you can specify dependencies inline, compared to builder v1 where you had to specify dependencies in a requirements.yml file. v3 gives you both options — either specify inline or point to a requirements file.

A mandatory bit you need to add to your execution-environment definition — if you are building on top of minimal or supported EE — is the package_manager_path. You need to do this because the downstream platform images are built on top of UBI-minimal, which uses microdnf instead of dnf. If you are using builder to build images on top of only UBI, Fedora, or CentOS, you do not need to specify the package_manager_path.

But as we are building on top of the minimal image, go ahead and add the following lines after the dependencies section:

Go ahead and save this file using Ctrl + S or from the File → Save option in the menu bar.

This concludes building our definition file. Now let’s go to the terminal window and type the following command to build our EE:

A bit about the command: we are not specifying the definition file name as we used the default name, and -v 3 signifies the verbosity level of the output. You will see the build steps when you run this command. Adding -v 3 is optional.

This command will take a minute or two to complete.

Run the following command to check the image that was created:

You will see that it builds an execution environment called local/ansible-execution-env by default — this is our EE built with the collection we specified. You can also specify the name for your EE by adding a tag to the build command, for example:

You can also tag the image post-build using Podman:

To verify if our EE was built correctly, run the following command to go inside the container image:

Once you are inside the EE, run the collection list command to check if the collection is present inside the EE:

The output should show the ansible.netcommon collection. Use the same method for all subsequent challenges to verify your EE.

🎉 Hurray! You have now created a basic execution environment. In the next challenge, we will look at how to pull collections from Automation Hub.

Press the Next button below to go to the next challenge once you’ve completed the tasks.

If you have encountered an issue or noticed something not quite right, please open an issue here:

https://github.com/ansible/workshops/issues