Creating Custom Execution Environments

5 Creating Custom Execution Environments

The builder utility allows you to customize and create execution environments that you can upload to Private Automation Hub where Oracle Linux Automation Manager can access them and use them to run playbooks. Being able to use customized container images as execution environments to run playbooks allows you to ensure you have all the packages and dependencies you need on the container image necessary to run playbooks in a consistent and dependable way.

Note:

While the Builder utility enables you to create custom execution environments, in the case of an issue with the custom execution environment, Oracle support may ask you to revert to the Oracle provided OLAM-EE default image to troubleshoot the problem.

Execution environments that you customize with the Builder utility contains:

The base OLAM-EE container image accessible from the Oracle Container Registry. Two versions of this container image are available where the main version includes the OCI SDK and the Ansible OCI Collection and the minimal version does not. Because the Ansible OCI Collection is updated on a more regular cadence to take advantage of new OCI features, the main version of thie OLAM-EE container image releases new more frequently updates.
A special builder image required for images created with the Builder utility that's also accessible from the Oracle Container Registry. The Builder utility uses this image when compiling container images.
One or more ansible collections.
Python or system dependencies (for example, modules, plugins in collections, custom scripts, bash commands), or a combination of both.

You can use the Builder utility to create execution environments with format version 1, 2, or 3. For examples, see Configuring a Custom Execution Environment Using Format 1, Configuring a Custom Execution Environment Using Format 2, and Configuring a Custom Execution Environment Using Format 3.

The default olam-ee available on the Oracle Container Registry uses the latest version of the Oracle Linux 8 container image. When building custom execution environments, we always use the latest version available of ansible-core and its python dependencies for the Oracle Linux 8 release provided. For more information about olam-ee and Python dependencies, see Oracle Linux Automation Manager 2.3: Release Notes.

In some cases, you might need a different version of Python not available on the default execution environment to run job templates for the playbook to work. To change the python version used by the playbook, apply the ansible_python_interpreter variable in the Oracle Linux Automation Manager UI. For example,

"ansible_python_interpreter: /usr/bin/python<version>"

In the previous example, version is the python version the playbook needs.

For more information about setting variables on job templates, see the Oracle Linux Automation Manager 2.3: User's Guide.

Configuring a Custom Execution Environment Using Format 1

To configure a custom execution environment using format 1, do the following:

On the host where you have installed the Builder utility, create a working directory for Builder utility. For example,
```
mkdir ~/builder-utility 
cd ~/builder-utility
```

Create the following files:

touch ansible.cfg execution-environment.yml requirements.yml requirements.txt bindep.txt

In the execution-environment.yml file, add the following parameters:
```
---
version: 1
build_arg_defaults:
  EE_BASE_IMAGE: 'container-registry.oracle.com/oracle_linux_automation_manager/olam-ee:2.3-<OS_Version>'
  EE_BUILDER_IMAGE: 'container-registry.oracle.com/oracle_linux_automation_manager/olam-builder:2.3-<OS_Version>'
  ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: "--ignore-certs"
ansible_config: 'ansible.cfg'
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
```
In the previous example,
- EE_BASE_IMAGE: This parameter requires the base olam-ee, which you can obtain from container-registry.oracle.com/oracle_linux_automation_manager/olam-ee:2.3-<OS_version>where OS_version is ol8 or ol9 for Oracle Linux 8 or Oracle Linux 9. Alternatively, you can also obtain a copy of this image from Private Automation Hub if you have configured Private Automation Hub for this purpose.
  
  Note:
  Two versions of this container image are available on the Oracle Container Registry where the main version includes the OCI SDK and the Ansible OCI Collection and the minimal version does not. The version specified in the previous example uses the main version. For more information about the minimal version, see Oracle Linux Automation Manager 2.3: Release Notes.
- EE_BUILDER_IMAGE: This parameter requires the olam-builder image, which you can obtain from container-registry.oracle.com/oracle_linux_automation_manager/olam-builder-<OS_version> where OS_version is ol8 or ol9 for Oracle Linux 8 or Oracle Linux 9. The builder container image contains build libraries necessary to create customer execution environments. Alternatively, you can also obtain a copy of this image from Private Automation Hub if you have configured Private Automation Hub for this purpose.
- ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: Use the "--ignore-certs" option. This parameter allows you to obtain an image from a repository without using self signed certificates.
- ansible_config: You can specify the ansible.cfg file to pass a token and other settings for a private account to a Private Automation Hub server. Otherwise, the Builder utility uses ansible.galaxy to download Ansible collections. Listing the config file path as a string includes it as a build argument in the initial phase of the build.
- dependencies: This section is a dictionary value that defines the Ansible Galaxy, Python, and system dependencies that must be installed into the final container.
  
  Note:
  Any dependencies listed in this section that are outside of the Oracle Linux or Oracle Linux Automation Manager scope of coverage are outside of the scope of coverage for support.
  Valid keys for this section are as follows:
  - galaxy: This parameter is the path to a file that defines the collection dependencies. The Builder utility installs these with the ansible-galaxy collection install -r requirements.yml command. The supplied value may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
    The format for specifying a collection in the requirements.yml file can be as follows:
    --- collections: - name: <namespace>.<collection_name>
    In the previous example, <namespace> is the namespace of the collection (for example, oracle) and <collection_name> is the name of the collection to be installed (for example, oci). You can repeat this combination for each collection you want to use.
    You can also indicate a specific version, source type, and source location as follows:
    --- collections: - name <namespace>.<collection_name> version: <version_number or "<range_identifyer><version_number>" type: <source_type>
    In the previous example, <version_number> can be any collection version number. When specified with one or more <range_identifyer>, then the version number is always the most recent version of the collection possible within the range specified. For example, the following indicates that the version should be greater than or equal to 5.0.0, but less than 6.0.0:
    --- collections: - name: oracle.oci version: ">=5.0.0,<6.0.0" type: galaxy
    You can use the following range identifiers:
    
    *
    The most recent version. This is the default.
    
    !=
    Not equal to the version specified.
    
    ==
    Exactly the version specified.
    
    >=
    Greater than or equal to the version specified.
    
    >
    Greater than the version specified.
    
    <=
    Less than or equal to the version specified.
    
    <
    Less than the version specified.
  - python: This string value is the path to a file containing the Python dependencies to be installed with the pip install -r requirements.txt command. The supplied value may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
    The format for specifying a python dependency in the requirements.txt file can be as follows:
```
<someproject>
<someproject><version_specifier><version_number>
<someproject><version_specifier><version_number>,<version_specifier><version_number>
```
    In the previous example, <someproject> is the name of the project. You can specify the project name alone, which find the latest version of that project, or you can specify a project with one or more <version_identifier> and <verion_number> combinations to return a specific version of the project you want to install. For example:
    requests>=2.4.2 xmltodict azure-cli-core==2.11.1
    For more information about available version specifiers, see https://peps.python.org/pep-0440/#version-specifiers.
  - system: This string value is points to a bindep.txt requirements file. This will be processed by bindep and then passed to dnf, other platforms are not yet supported. For example:
```
gcc
libcurl-devel
libxml2-devel
python39-devel
openssl-devel
```
    Note:
    Some collections require different versions of Python to be installed. For example, the ovirt.ovirt collection requires python3.9-devel when installed on Oracle Linux 9 and python3.11-devel or possibly python3.12-devel when installed on Oracle Linux 8.
    
    For more information about writing a system requirements file and optionally specifying version constraints, see https://docs.opendev.org/opendev/bindep/latest/readme.html#writing-requirements-files.
- additional_build_steps: Additional commands may be specified in the additional_build_steps section, either for before the main build steps (prepend) or after (append). The syntax needs to be one of the following:
  - a multi-line string (example shown in the prepend section above)
  - a list (as shown via append)
Save the file.
Complete the ansible.cfg and any dependency files as required.
Run the following command from your working directory:
```
ansible-builder build -t <repository:tag>
```
In the previous example, <repository:tag> is the repository and tag of the custom execution environment. For example, <hostname.domain>/custom_ee:latest.

Note:
A warning message appears indicating that format 1 is deprecated. Consider using format 3 instead. For more information, see Configuring a Custom Execution Environment Using Format 3.
Note:
For more information as the builder utility processes, use the -v 3 option at the end of the command provides the most information while 1 is the least. For example,
```
ansible-builder build -v 3
```
Verify that the images have been created. Run the following Podman command:
```
podman images
```

Configuring a Custom Execution Environment Using Format 2

To configure a custom execution environment using format 2, do the following:

On the host where you have installed the Builder utility, create a working directory for Builder utility. For example,
```
mkdir ~/builder-utility 
cd ~/builder-utility
```

Create the following files:

touch ansible.cfg execution-environment.yml requirements.yml requirements.txt bindep.txt

In the execution-environment.yml file, add the following parameters:
```
---
version: 2

build_arg_defaults:
 ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: "--ignore-certs"

ansible_config: 'ansible.cfg'

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

images:
 base_image:
  name: container-registry.oracle.com/oracle_linux_automation_manager/olam-ee:2.3-<OS_version>
 builder_image:
  name: container-registry.oracle.com/oracle_linux_automation_manager/olam-builder:2.3-<OS_version>
```
In the previous example,
- ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: Use the "--ignore-certs" option.This parameter allows you to obtain an image from a repository without using self signed certificates.
- ansible_config: You can specify the ansible.cfg file to pass a token and other settings for a Private Automation Hub server. Listing the config file path as a string includes it as a build argument in the initial phase of the build.
- dependencies: This section is a dictionary value that is defines the Ansible Galaxy, Python, and system dependencies that must be installed into the final container. Valid keys for this section are as follows:
  - galaxy: This parameter is the path to a file that defines the collection dependencies. The Builder utility installs these with the ansible-galaxy collection install -r requirements.yml command. The supplied value may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
    The format for specifying a collection in the requirements.yml file can be as follows:
    --- collections: - name <namespace>.<collection_name>
    In the previous example, <namespace> is the namespace of the collection (for example, oracle) and <collection_name> is the name of the collection to be installed (for example, oci). You can repeat this combination for each collection you want to use.
    You can also indicate a specific version, source type, and source location as follows:
    --- collections: - <namespace>.<collection_name> version: <version_number or "<range_identifyer><version_number>" type: <source_type>
    In the previous example, <version_number> can be any collection version number. When specified with one or more <range_identifyer>, then the version number is always the most recent version of the collection possible within the range specified. For example, the following indicates that the version should be greater than or equal to 5.0.0, but less than 6.0.0:
    --- collections: - name: oracle.oci version: ">=5.0.0,<6.0.0" type: galaxy
    You can use the following range identifiers:
    
    *
    The most recent version. This is the default.
    
    !=
    Not equal to the version specified.
    
    ==
    Exactly the version specified.
    
    >=
    Greater than or equal to the version specified.
    
    >
    Greater than the version specified.
    
    <=
    Less than or equal to the version specified.
    
    <
    Less than the version specified.
  - python: This string value is the path to a file containing the Python dependencies to be installed with the pip install -r ... command. The supplied value may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
    The format for specifying a python dependency in the requirements.txt file can be as follows:
```
<someproject>
<someproject><version_specifier><version_number>
<someproject><version_specifier><version_number>,<version_specifier><version_number>
```
    In the previous example, <someproject> is the name of the project. You can specify the project name alone, which find the latest version of that project, or you can specify a project with one or more <version_identifier> and <verion_number> combinations to return a specific version of the project you want to install. For example:
    requests>=2.4.2 xmltodict azure-cli-core==2.11.1
    For more information about available version specifiers, see https://peps.python.org/pep-0440/#version-specifiers.
  - system: This string value is points to a bindep.txt requirements file. This will be processed by bindep and then passed to dnf, other platforms are not yet supported. For example:
```
gcc 
libcurl-devel 
libxml2-devel  
python39-devel 
openssl-devel 
```
    Note:
    Some collections require different versions of Python to be installed. For example, the ovirt.ovirt collection requires python3.9-devel when installed on Oracle Linux 9 and python3.11-devel or possibly python3.12-devel when installed on Oracle Linux 8.
    
    For more information about writing a system requirements file and optionally specifying version constraints, see https://docs.opendev.org/opendev/bindep/latest/readme.html#writing-requirements-files.
- additional_build_steps: Additional commands may be specified in the additional_build_steps section, either for before the main build steps (prepend) or after (append). The syntax needs to be one of the following:
  - a multi-line string (example shown in the prepend section above)
  - a list (as shown via append)
- images: You can use the images key to define base and builder images. With the version 2 format, an execution environment definition may specify a base and builder container image whose signature must be validated before builder will build the resulting image, based on the value of the --container-policy CLI option. Key options are as follows:
  - base_image: This parameter requires the base olam-ee, which you can obtain from container-registry.oracle.com/oracle_linux_automation_manager/olam-ee:2.3-<OS_version> where OS_version is ol8 or ol9 for Oracle Linux 8 or Oracle Linux 9. Alternatively, you can also obtain a copy of this image from Private Automation Hub if you have configured Private Automation Hub for this purpose.
    
    Note:
    Two versions of this container image are available on the Oracle Container Registry where the main version includes the OCI SDK and the Ansible OCI Collection and the minimal version does not. The version specified in the previous example uses the main version. For more information about the minimal version, see Oracle Linux Automation Manager 2.3: Release Notes.
  - builder_image: This parameter requires the olam-builder image, which you can obtain from container-registry.oracle.com/oracle_linux_automation_manager/olam-builder:2.3-<OS_version> where OS_version is ol8 or ol9 for Oracle Linux 8 or Oracle Linux 9. The builder container image contains build libraries necessary to create customer execution environments. Alternatively, you can also obtain a copy of this image from Private Automation Hub if you have configured Private Automation Hub for this purpose.
Save the file.
Complete the ansible.cfg and any dependency files as required.
Run the following command from your working directory:
```
ansible-builder build -t <repository:tag>
```
In the previous example, <repository:tag> is the repository and tag of the custom execution environment. For example, <hostname.domain>/custom_ee:latest.

Note:
A warning message appears indicating that format 2 is deprecated. Consider using format 3 insteadl. For more information, see Configuring a Custom Execution Environment Using Format 3.
Note:
For more information as the builder utility processes, use the -v 3 option at the end of the command provides the most information while 1 is the least. For example,
```
ansible-builder build -v 3
```
Verify that the images have been created. Run the following Podman command:
```
podman images
```

Configuring a Custom Execution Environment Using Format 3

To configure a custom execution environment using format 3, do the following:

On the host where you have installed the Builder utility, create a working directory for Builder utility. For example,
```
mkdir ~/builder-utility 
cd ~/builder-utility
```

Create the following files:

touch ansible.cfg execution-environment.yml requirements.yml requirements.txt bindep.txt

In the execution-environment.yml file, add the following parameters:
```
---
version: 3

build_arg_defaults:
  ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: '--pre --ignore-certs'


dependencies:
  ansible_runner:
    package_pip: ansible-runner
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt

images:
  base_image:
    name: container-registry.oracle.com/oracle_linux_automation_manager/olam-ee:2.3-<OS_version>

additional_build_files:
    - src: ansible.cfg
      dest: configs

additional_build_steps:
  prepend_galaxy:
    - COPY _build/configs/ansible.cfg /etc/ansible/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 previous example,
- ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: Use the "--ignore-certs" option.This parameter allows you to obtain an image from a repository without using self signed certificates.
- dependencies: This section is a dictionary value that is defines the Ansible Galaxy, Python, and system dependencies that must be installed into the final container. Valid keys for this section are as follows:
  - ansible_runner: package_pip: ansible-runner: During the base build stage, the ansible-runner component is customized to be installed by the package_pip Python installer. Ephemeral copies of the resulting customized base image are used as the base for all other build stages.
  - galaxy: This parameter is the path to a file that defines the collection dependencies. The Builder utility installs these with the ansible-galaxy collection install -r requirements.yml command. The supplied value may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
    The format for specifying a collection in the requirements.yml file can be as follows:
    --- collections: - name <namespace>.<collection_name>
    In the previous example, <namespace> is the namespace of the collection (for example, oracle) and <collection_name> is the name of the collection to be installed (for example, oci). You can repeat this combination for each collection you want to use.
    You can also indicate a specific version, source type, and source location as follows:
    --- collections: - name: <namespace>.<collection_name> version: <version_number or "<range_identifyer><version_number>" type: <source_type>
    In the previous example, <version_number> can be any collection version number. When specified with one or more <range_identifyer>, then the version number is always the most recent version of the collection possible within the range specified. For example, the following indicates that the version should be greater than or equal to 5.0.0, but less than 6.0.0:
    --- collections: - name: oracle.oci version: ">=5.0.0,<6.0.0" type: galaxy - name: ovirt.ovirt
    You can use the following range identifiers:
    
    * The most recent version. This is the default.
    
    != Not equal to the version specified.
    
    == Exactly the version specified.
    
    >= Greater than or equal to the version specified.
    
    > Greater than the version specified.
    
    <= Less than or equal to the version specified.
    
    < Less than the version specified.
  - python: This string value is the path to a file containing the Python dependencies to be installed with the pip install -r ... command. The supplied value may be a relative path from the directory of the execution environment definition’s folder, or an absolute path.
    The format for specifying a python dependency in the requirements.yml file can be as follows:
```
<someproject>
<someproject><version_specifier><version_number>
<someproject><version_specifier><version_number>,<version_specifier><version_number>
```
    In the previous example, <someproject> is the name of the project. You can specify the project name alone, which find the latest version of that project, or you can specify a project with one or more <version_identifier> and <verion_number> combinations to return a specific version of the project you want to install. For example:
    requests>=2.4.2 xmltodict azure-cli-core==2.11.1
    For more information about available version specifiers, see https://peps.python.org/pep-0440/#version-specifiers.
  - system: This string value is points to a bindep.txt requirements file. This is processed by bindep and then passed to dnf, other platforms are not yet supported. For example:
```
gcc 
libcurl-devel 
libxml2-devel  
python39-devel 
openssl-devel 
```
    Note:
    Some collections require different versions of Python to be installed. For example, the ovirt.ovirt collection requires python3.9-devel when installed on Oracle Linux 9 and python3.11-devel or possibly python3.12-devel when installed on Oracle Linux 8.
    For more information about writing a system requirements file and optionally specifying version constraints, see https://docs.opendev.org/opendev/bindep/latest/readme.html#writing-requirements-files.
- images: You can use the images key to define a base image. With the version 3 format, an execution environment definition may specify a base container image whose signature must be validated before builder will build the resulting image, based on the value of the --container-policy CLI option. The key options is base_image. This parameter requires the base olam-ee, which you can obtain from container-registry.oracle.com/oracle_linux_automation_manager/olam-ee:2.3-<OS_version> where OS_version is ol8 or ol9 for Oracle Linux 8 or Oracle Linux 9. Alternatively, you can also obtain a copy of this image from Private Automation Hub if you have configured Private Automation Hub for this purpose.
  
  Note:
  Two versions of this container image are available on the Oracle Container Registry where the main version includes the OCI SDK and the Ansible OCI Collection and the minimal version does not. The version specified in the previous example uses the main version. For more information about the minimal version, see Oracle Linux Automation Manager 2.3: Release Notes.
- additional_build_files: You can specify a ansible.cfg file to pass a token and other settings for a Private Automation Hub server. This file is referenced using the following format:
```
additional_build_files:
    - src: ansible.cfg
      dest: configs
```
  Note:
  If you omitting specifying the credentials for an Private Automation Hub in the ansible.cfg file, then Private Automation Hub defaults to the public https://galaxy.ansible.com.
- additional_build_steps: Additional commands may be specified in the additional_build_steps section, either for before the build stages (prepend) or after (append). These stages include the following:
  Base Build Stage: Customizes the specified base image with required components such as Python, pip, ansible-core, and ansible-runner. Validates the presence of these components. Creates ephemeral copies of the customized base image for subsequent stages. Steps include:
  - prepend_base: Insert commands before customizing the base image.
  - append_base: Insert commands after customizing the base image.
  Galaxy Build Stage: Downloads and stores collections specified in the definition file. Collects Python and system dependencies declared by the collections. Steps include:
  - prepend_galaxy: Insert commands before downloading collections.
  - append_galaxy: Insert commands after downloading collections.
  Builder Build Stage: Merges Python dependencies from collections and the definition file. Downloads and builds Python dependencies as wheels. Stores the wheels for later installation. Steps include:
  - prepend_builder: Insert commands before merging Python dependencies.
  - append_builder: Insert commands after building Python wheels.
  Final Build Stage: Installs previously-downloaded collections. Installs system packages and Python packages built during the builder stage. Steps include:
  - prepend_final: Insert commands before installing collections and packages.
  - append_final: Insert commands after installing collections and packages.
  By injecting custom commands at each stage, you can tailor the image creation process to meet specific requirements or integrate with other tools and systems.
Save the file.
Complete the ansible.cfg and any dependency files as required.
Run the following command from your working directory:
```
ansible-builder build -t <repository:tag>
```
In the previous example, <repository:tag> is the repository and tag of the custom execution environment. For example, <hostname.domain>/custom_ee:latest.
Note:
For more information as the builder utility processes, use the -v 3 option at the end of the command provides the most information while 1 is the least. For example,
```
ansible-builder build -v 3
```
Verify that the images have been created. Run the following Podman command:
```
podman images
```

Uploading a Custom Execution Environment

To upload a custom execution environment, do the following:

From the host where you created the custom execution environment, use Podman to log into the Private Automation Hub instance you want to upload your custom execution environment to. For example,
```
podman login <ip address or hostname> -u admin -p <password> --tls-verify=false
```
In the previous example, <ip address or hostname> is the IP address or host name of the Private Automation Hub instance and <password> is the password for the admin user on the Private Automation Hub instance.
Identify which custom image you want to upload. For example,
```
podman images
```
Push the image to your Private Automation Hub. For example,
```
podman push <podman_image_id or repository:tag> <ip address or hostname/image_name:tag> --tls-verify=false
```
In the previous example, <podman_image_id or repository:tag> is the image ID or the repository and tag of the custom execution environment you want to push and <ip address or hostname/image_name:tag> is the IP address or host name followed by the image name and the tag of the Private Automation Hub instance. For example, the following uses a podman repository name and tag followed by the hostname, image name, and tag to use on the private automation hub instance:
```
podman push localhost/custom-image:2.1.3 private_automation_hub_host/custom-image:2.1.3 --tls-verify=false
```
The following uses a podman image id followed by the hostname, image name, and tag to use on the private automation hub instance:
```
podman push 330928308c01 private_automation_hub_host/custom-image:2.1.3 --tls-verify=false
```
Verify that the execution environment now exists on your Private Automation Hub instance. For more information about this task, see View Execution Environment Details.