Use Custom Execution Environment with Oracle Linux Automation Manager

Introduction

Through the use of a custom execution environment (ee), Oracle Linux Automation Manager can leverage playbooks containing collections and other resources not available with the default olam-ee image. You build it using the Builder utility, store it on Private Automation Hub, and then pull it into Oracle Linux Automation Manager.

So, how does that all work together?

This tutorial shows how to upload a pre-built image to Private Automation Hub and then pull it into Oracle Linux Automation Manager for running playbooks. For details on creating customized execution environments, see our tutorial on the Builder utility, and this tutorial on Private Automation Hub.

Objectives

In this lab, you'll learn how to:

Push a custom ee to Private Automation Hub using a playbook
Add a custom ee to Oracle Linux Automation Manager
Use the custom ee to run a Job

Prerequisites

Three systems running Oracle Linux
- A development environment using the Builder utility
- One for Private Automation Hub
- Another for running Oracle Linux Automation Manager

Push Custom Execution Environment to Private Automation Hub

One method to push a custom ee to the Private Automation Hub is using podman from the command line, as shown in the Private Automation Hub tutorial. It is also possible to perform this task with a playbook and using the containers.podman collection.

Note: When using the free lab environment, see Oracle Linux Lab Basics for connection and other usage instructions.

Information: The free lab environment deploys Oracle Linux Automation Manager, Builder utility, and Private Automation Hub. The deployment takes approximately 40 minutes to finish after launch. Therefore, you might want to step away while this runs and promptly return to complete the lab.

Open a terminal and connect via ssh to the devops-node instance.
```
ssh oracle@<ip_address_of_devops-node>
```
Install Oracle Linux Automation Engine.
```
sudo dnf install ansible-core -y
```

Install the required collections.

ansible-galaxy collection install containers.podman

Create the playbook to tag and push the custom ee image.

tee push-image.yml > /dev/null <<EOF
---
- hosts: localhost
  collections:
    - containers.podman

  tasks:

  - name: get domain_name
    command: hostname -d
    register: domain_name

  - name: output domain_name var
    debug:
      msg: "{{domain_name.stdout}}"

  - name: tag image for upload
    containers.podman.podman_tag:
      image: localhost/my_custom_ee
      target_names:
        - ol-pah.{{domain_name.stdout}}/my_first_olam_ee_image

  - name: push image to pah
    containers.podman.podman_image:
      name: ol-pah.{{domain_name.stdout}}/my_first_olam_ee_image:latest
      push: true
      push_args:
        dest: ol-pah.{{domain_name.stdout}}
      username: admin
      password: password
      validate_certs: false
EOF

Run the playbook.
```
ansible-playbook push-image.yml
```
The playbook runs on localhost and, therefore, does not need an inventory file defined.

Verify Image Exists in Private Automation Hub

Open a new terminal from the Luna Desktop.
Configure an SSH tunnel to Private Automation Hub.
```
ssh -L 5444:localhost:443 oracle@<ip_address_of_ol-pah>
```
In the free lab environment, use the IP address of the ol-pah VM.
Open a web browser and enter the URL.
```
https://localhost:5444
```
Note: Approve the security warning based on the browser used. For Chrome, click the Advanced button and then the Proceed to localhost (unsafe) link.
Log in to the Private Automation Hub WebUI.
Use the Username admin and the Password password. The free lab environment sets this password value during the lab deployment.
The WebUI displays after a successful login.
Click the navigation menu in the upper left corner of the Private Automation Hub WebUI.
Navigate to Execution Environments and Execution Environments.
Notice the new my_first_olam_ee_image displays in the main panel.

Create a Playbook

Administrators of Oracle Linux Automation Manager can create playbooks locally on the file system, which a Project using Manual Source Control can leverage. We'll use the devops-node to write a playbook that pushes our Project playbook to Oracle Linux Automation Manager using Oracle Linux Automation Engine.

Switch to or open a terminal and connect via ssh to the devops-node instance.
Create a project directory and change the working directory to it.
```
mkdir ~/project1
cd ~/project1
```

Create a template.

This template is the playbook file we'll write to the file system on the Oracle Linux Automation Manager server to retrieve the list of container images on a host.

mkdir templates
tee templates/list-images.yml.j2 > /dev/null <<EOF
---
- hosts: all
  collections:
    - containers.podman
  become: yes

  tasks:

  - name: gather info on images
    containers.podman.podman_image_info:
    register: podman_list
    become_user: oracle

  - name: list images
    debug:
      msg: "{{'{{'}} podman_list.images | selectattr('RepoTags') {{'}}'}}"
EOF

Create a playbook to push this project to Oracle Linux Automation Manager.

tee push-project.yml > /dev/null <<EOF
---
- hosts: ol-node
  become: yes

  tasks:

  - name: create project directory
    ansible.builtin.file:
      path: /var/lib/awx/projects/podman
      state: directory
    become_user: awx

  - name: create playbook
    ansible.builtin.template:
      src: templates/list-images.yml.j2
      dest: /var/lib/awx/projects/podman/list-images.yml
    become_user: awx
EOF

Create an inventory file.

tee hosts > /dev/null <<EOF
[olam]
ol-node
EOF

Copy the playbook to the Oracle Linux Automation Manager server.
```
ansible-playbook -i hosts push-project.yml
```

Add a Custom Execution Environment to Oracle Linux Automation Manager

Log into the WebUI

Open a new terminal from the Luna Desktop.
Configure an SSH tunnel to Oracle Linux Automation Manager.
```
ssh -L 8444:localhost:443 oracle@<ip_address_of_ol-node>
```
In the free lab environment, use the IP address of the ol-node VM.
Open a web browser and enter the URL.
```
https://localhost:8444
```
Note: Approve the security warning based on the browser used. For Chrome, click the Advanced button and then the Proceed to localhost (unsafe) link.
Log in to the Oracle Linux Automation Manager WebUI.
Use the Username admin and the Password admin. The free lab environment sets this password value during the lab deployment.
The WebUI displays after a successful login.

Add a Container Registry Credential

Click Credentials under Resources in the navigation menu.
Click the Add button in the main panel.
Enter or select the following values in the specific fields.
For fields with a search or list of values, we can start typing the requested value and then select it.
- Name: My Private Automation Hub
- Organization: Default
- Credential Type: Container Registry
- Authentication URL: the FQDN for the Private Automation Hub
- Username: admin
- Password or Token: password
- Options: uncheck Verify SSL
Note: If you do not know the FQDN for the Private Automation Hub, use a terminal to connect to the ol-pah VM and then run hostname -f.
Oracle Linux Automation Manager uses the Container Registry credentials to access container images in Private Automation Hub. The free lab environment requires unchecking the Verify SSL setting due to its use of self-signed certificates.
Review the entries and click the Save button.

Add an Execution Environment

Click Execution Environments under Administration in the navigation menu.
Click the Add button in the main panel.
Enter or select the following values in the specific fields.
For fields with a search or list of values, we can start typing the requested value and then select it.
- Name: My Custom EE
- Image: <fqdn_of_the_private_automation_hub>/my_first_olam_ee_image:latest
- Registry credential: My Private Automation Hub
Review the entries and click the Save button.

Test the Execution Environment

When testing the custom execution environment, a Job Template is required, which includes an Inventory, Hosts, Machine Credentials, and a Project.

Add an Inventory

Click Inventories under Resources in the navigation menu.
Click the Add button in the main panel and select Add inventory from the list of values.
Enter the following value in the specific field.
- Name: Oracle Linux Hosts
Review the entry and click the Save button.

Add a Host

Click the Hosts tab from the Oracle Linux Hosts Inventory Details panel.
Click the Add button.
Enter the hostname devops-node into the Name field
Review the entry and click the Save button.

Add a Machine Credential

Click Credentials under Resources in the navigation menu.
Click the Add button in the main panel.
Enter or select the following values in the specific fields.
For fields with a search or list of values, we can start typing the requested value and then select it.
- Name: Oracle Linux SSH Access
- Organization: Default
- Credential Type: Machine
- Username: opc
- SSH Private Key: select the id_rsa key from the ~/.ssh directory
Note: One way to grab the SSH Private Key is to select the Browse option for that field. In the File Upload dialog, select Home and then right-click on the main window of that dialog. Select Show Hidden Files. Select the .ssh folder and the id_rsa file. Clicking the Open button causes the contents of the private key file to copy into the SSH Private Key dialog box.
Review the entries, scroll to the bottom of the page, and click the Save button.

Create a New Project

Click Projects under Resources in the navigation menu.
Click the Add button in the main panel.
Enter or select the following values in the specific fields.
For fields with a search or list of values, we can start typing the requested value and then select it.
- Name: Container Management
- Execution Environment: My Custom EE
- Source Control Credential Type: Manual
- Playbook Directory: podman
Review the entries and click the Save button.

Add a Job Template

Click Templates under Resources in the navigation menu.
Click the Add button in the main panel and select Add job template from the list of values.
Enter or select the following values in the specific fields.
For fields with a search or list of values, we can start typing the requested value and then select it.
- Name: List Images
- Job Type: Run
- Inventory: Oracle Linux Hosts
- Project: Container Management
- Execution Environment: My Custom EE
- Playbook: list-images.yml
- Credentials: Oracle Linux SSH Access
Review the entries, scroll to the bottom of the page, and click the Save button.

Run the Template

Click Templates under Resources in the navigation menu.
Click the Launch Template icon in the Actions column next to the List Images Job Template.

The Job starts, and the panel switches to the Job Output summary. After a few minutes, the Job fails.

olam2-job-failure

This failure occurs because the new custom ee does not contain the containers.podman collection, so the playbook fails to run.

Fix the Custom Execution Environment

To fix the custom ee, we must rebuild the container image using the Builder utility and then push the new image to Private Automation Hub for pickup by Oracle Linux Automation Manager.

Switch to or open a terminal and connect via ssh to the devops-node instance.
Change to the custom ee project directory.
```
cd ~/my_custom_ee_project
```

Add the missing collection to the Ansible Galaxy requirements file.

tee -a requirements.yml > /dev/null <<EOF
- name: containers.podman
EOF

Rebuild the image.

ansible-builder build --tag my_custom_ee -v 3

Push the new image to Private Automation Hub.
```
cd ~
ansible-playbook push-image.yml
```
(Optional) Verify a successful image push.
Connect to the Private Automation Hub WebUI and review the Execution Environment changes, specifically the Last modified column for the my_first_olam_ee_image.

Test the New Custom Execution Environment

Switch in the browser to the Oracle Linux Automation Manager WebUI.
Refresh the browser window and log in again if necessary.
Click Execution Environments under Administration in the navigation menu.
Click the Edit Execution Environment icon under the Actions column next to the My Custom EE image link.
Change the Pull value to Always pull container before running.
This field enables the --pull option for podman. The setting change will force Oracle Linux Automation Manager to pull the latest image when its layer checksums do not match.
Review changes and click the Save button.
Click Jobs under Views in the navigation menu.
Click the Relaunch icon under the Actions column next to the ...List Images link.
Select All from the drop-down list of values.
The Job starts, and the panel switches to the Job Output summary. After a few minutes, the Job completes successfully.

Summary

The output within the WebUI confirms you have a working custom execution environment within Oracle Linux Automation Manager.

For More Information

Oracle Linux Automation Manager Documentation Oracle Linux Automation Manager Training Oracle Linux Training Station