Configure Podman Containers with Oracle Linux Automation Engine

Introduction

Oracle Linux Automation Engine enables users to create a playbook for installing Podman and then running and managing containers using the containers.podman collection.

When running playbooks, Oracle Linux Automation Engine runs the tasks on machines matching the hosts: directive in the playbook. These hosts are typically defined in an inventory file and can either be remote or local. In this tutorial, we'll demonstrate how to run a playbook locally.

Objectives

In this tutorial, you'll learn to:

Run playbooks locally
Add a collection to a playbook
Install Podman
Pull and run an oraclelinux:8 container

Prerequisites

An Oracle Linux system with the following configuration:
- a non-root user with sudo permissions
- install Oracle Linux Automation Engine

Deploy Oracle Linux Automation Engine

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

Open a terminal on the Luna Desktop.

Clone the linux-virt-labs GitHub project.

git clone https://github.com/oracle-devrel/linux-virt-labs.git

Change into the working directory.
```
cd linux-virt-labs/olam
```

Install the required collections.

ansible-galaxy collection install -r requirements.yml

Update the Oracle Linux instance configuration.

cat << EOF | tee instances.yml > /dev/null
compute_instances:
  1:
    instance_name: "ol-control-node"
    type: "control"
use_olae_only: true
EOF

Deploy the lab environment.
```
ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e "@instances.yml"
```
The free lab environment requires the extra variable local_python_interpreter, which sets ansible_python_interpreter for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules.
The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.
Important: Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Linux is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab.

Collections

Collections are a distribution format for Oracle Linux Automation Engine content that can include playbooks, roles, modules, and plugins. This tutorial will install the containers.podman collection using a requirements.yml file. A requirements.yml file allows for installing collections, roles, or both based on the keys defined within the file.

Create a Requirements File

Open a new terminal and connect via SSH to the ol-control-node system.
```
ssh oracle@<ip_address_of_instance>
```
Create a working directory.
```
mkdir -p ~/podman-project
```

Create a requirements file.

cat << 'EOF' | tee ~/podman-project/requirements.yml > /dev/null
---
collections:
  - name: containers.podman
EOF

Install the collection.
```
ansible-galaxy collection install -r ~/podman-project/requirements.yml
```
The output shows the process of retrieving the compressed archive file from the Galaxy site and then installing it into your home directory under .ansible/collections.
Note: If the output shows ERROR: Ansible requires the locale encoding to be UTF-8; Detected None., this indicates an incorrect locale setting for ansible. Fix the issue by setting these two environment variables:
```
export LC_ALL="en_US.UTF-8"
export LC_CTYPE="en_US.UTF-8"
```

Install Podman

Oracle Linux Automation Engine playbooks consist of plays made up of tasks mapped to hosts. These tasks primarily run idempotent modules. Idempotency is getting the same result whether running the playbook once or multiple times. This tutorial will demonstrate idempotency by building the playbook in stages and running it between each change.

Before running a Podman container, we need to install the Podman packages. We'll install the packages using the container-tools:ol8 module from the Oracle Linux ol8_appstream repository.

Create the playbook file.
```
cat << 'EOF' | tee ~/podman-project/podman-playbook.yml > /dev/null
---
- hosts: localhost
  connection: local
  
  tasks:
  
  - name: Install podman
    ansible.builtin.dnf:
      name: '@container-tools:ol8'
      state: present
    become: yes
EOF
```
A playbook and the names of the tasks aim to make the playbook self-documenting. The information below will explain a few items further.
- hosts: localhost: Instructs the tasks to run against the localhost.
- connection: local: Ensures the link remains local and does not run over SSH.
- collections: Provides a list of any collections used in the play.
- become: yes: Elevates the task within this playbook section to be run with the sudo privilege by default.
Run the playbook.
Since we run this playbook against the local host, there is no reason to create or reference an inventory file explicitly. However, if we wanted to run this against a remote host, we would need to update the hosts: entry, remove the connection: line in the playbook, and then create and reference an inventory file. If you are not familiar with this process, you can check out some of our other tutorials linked in the Oracle Linux Training Station at the end of this tutorial.
```
ansible-playbook ~/podman-project/podman-playbook.yml
```
The command's output should show it runs successfully against localhost, reporting a change in the Install podman task. This status indicates that we have appropriately completed the installation of the container-tools module.
Verify the Podman package installed by displaying its version.
```
podman --version
```

Pull an Image

Once we've installed Podman, we can pull images from our registry of choice and stage them locally. In this step, we'll pull the Oracle Linux image from the GitHub Container Registry.

Additional information regarding Oracle Linux Developer images is available here .

Add the task to pull a container image to the playbook.

cat << EOF | tee -a ~/podman-project/podman-playbook.yml > /dev/null

  - name: Pull oraclelinux:8 from GitHub
    containers.podman.podman_image:
      name: ghcr.io/oracle/oraclelinux:8
EOF

Run the playbook.

ansible-playbook ~/podman-project/podman-playbook.yml

Verify that Podman pulled the image.

podman images

Example output:

REPOSITORY                  TAG         IMAGE ID      CREATED       SIZE
ghcr.io/oracle/oraclelinux  8           97e22ab49eea  20 hours ago  254 MB

Run a Container Image

Rather than just pulling an image, we can also pull and run a container based on an image in a single step. Let's pull and run the Oracle Linux NGINX developer image.

Update the playbook file.
```
cat << EOF | tee -a ~/podman-project/podman-playbook.yml > /dev/null

  - name: Run image
    containers.podman.podman_container:
      name: my-ol8
      image: ghcr.io/oracle/oraclelinux8-nginx:1.18
      state: started
      detach: yes
      expose:
        - '80'
        - '443'
      publish:
        - '8080:80'
EOF
```
Where:
- name: Name of the container.
- image: Repository path (or image name) and tag used to create the container.
- state: Checks for a running container matching the name and configuration. Podman creates and starts a new container when not finding a match.
- detach: Runs the container in detached mode.
- expose: Expose a port or a range of ports.
- publish: Publish a container's port, or range of ports, to the host.

Run the playbook.

ansible-playbook ~/podman-project/podman-playbook.yml

Verify the container is running.

podman ps

Example output:

[oracle@ol-server podman-project]$ podman ps
CONTAINER ID  IMAGE                                   COMMAND               CREATED         STATUS             PORTS                 NAMES
5f7a28cc4c6b  ghcr.io/oracle/oraclelinux8-nginx:1.18  nginx -g daemon o...  2 minutes ago   Up 2 minutes ago   0.0.0.0:8080->80/tcp  my-ol8

The output shows the container has been up and running for 2 minutes.

Stop the container.
Using the CONTAINER ID from the output above, run:
```
podman stop $(podman ps -q -f name=my-ol8)
```
This command uses the CONTAINER ID as the reference to stop the my-ol8 container.

Run a Container Image with a Volume

Podman creates volumes by adding a bind mount mapping a local directory to a directory within the container. We'll demonstrate this feature by running the same NGINX container and substituting a custom index.html page for the NGINX default.

Update the playbook file.

Create the local directory. While we can efficiently and manually perform this step one time from the command line, let's automate it instead. Automating this step ensures the directory exists anytime the playbook runs. Before running the image, add these tasks, which create a directory and the index.html file.

Ensure you leave a blank line between tasks for readability and follow YAML syntax rules and alignment. We'll use sed to complete this task as it allows the easy insertion of blocks of text into a file on a specific line.

sed -i -e '16 r '<(cat -<< EOF
  - name: Ensure dest directory exists
    ansible.builtin.file:
      path: "/home/oracle/nginx/"
      state: directory

  - name: Create empty file
    ansible.builtin.file:
      path: "/home/oracle/nginx/index.html"
      state: touch
      mode: '0755'

  - name: Create index.html
    ansible.builtin.copy:
      dest: "/home/oracle/nginx/index.html"
      content: |
        Hello! Welcome to Oracle Linux Containers.

EOF
) ~/podman-project/podman-playbook.yml

Then add the following option at the end of the Run image task.
```
cat << EOF | tee -a ~/podman-project/podman-playbook.yml > /dev/null
      volume: "/home/oracle/nginx:/usr/share/nginx/html:Z"
EOF
```
The volume option creates a bind mount between the source:destination directory. The :Z option addresses any SELinux permissions issues related to the bind mount. Podman does this by relabeling the volume's content to match the label inside the container.
Here
```
https://luna.oracle.com/api/v1/labs/6154cf89-6a6e-45b3-98ad-635979b953e8/gitlab/tutorial/files/podman-playbook.yml
```
is a completed version of the playbook for reference.

Run the playbook.

ansible-playbook ~/podman-project/podman-playbook.yml

Verify the container is running.

podman ps

Example output:

CONTAINER ID  IMAGE                                   COMMAND               CREATED         STATUS             PORTS                 NAMES
f74aa726d470  ghcr.io/oracle/oraclelinux8-nginx:1.18  nginx -g daemon o...  10 minutes ago  Up 10 minutes ago  0.0.0.0:8080->80/tcp  my-ol8

Verify the index.html file exists.

ls -l /home/oracle/nginx

Example output:

[oracle@ol-server podman-project]$ ls -l /home/oracle/nginx/
total 4
-rwxr-xr-x. 1 oracle oracle 41 Nov  5 16:46 index.html

Verify the bind mount.
Use cURL to display the index.html page from the container and the Welcome message.
```
curl localhost:8080
```
Where 8080 is the local port mapping to port 80 in the container.

Next Steps

By completing this tutorial, you should understand how to automate your work with Podman and containers using Oracle Linux Automation Engine. Explore the other modules in the containers.podman collection to create additional playbooks that automate your infrastructure.