Configure Podman Containers with Oracle Linux Automation Engine

Introduction

This tutorial guides you through creating a playbook for installing Podman and running an Oracle Linux container using the configuration management tool Oracle Linux Automation Engine.

Before proceeding: If you are not familiar with running playbooks, check out our introduction tutorial, Write a Playbook with Oracle Linux Automation Engine .

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 lab, 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

Collections

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

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

If not already connected, open a terminal and connect via ssh to the ol-server system.
```
ssh oracle@<ip_address_of_ol-server>
```
Create a working directory.
```
mkdir -p ~/podman-project
```
Change to the working directory.
```
cd ~/podman-project
```
Create the requirements.yml file using your editor of choice. Here, we'll use vi.
```
vi requirements.yml
```
Enter vi insert mode by typing i.
Add the key and name of any collections used within the playbook.
Example:
```
---
collections:
  - name: containers.podman
```
Once you finish editing the requirements.yml file, save and close the file. If using vi, you can do that by typing ESC, :wq!, and ENTER.

Install the Collections using the Requirements File

Pull the collections and install them locally.

ansible-galaxy collection install -r requirements.yml

After the command runs successfully, the results are similar to those shown.

Example output:

[oracle@ol-server podman-project]$ ansible-galaxy collection install -r requirements.yml 
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://galaxy.ansible.com/download/containers-podman-1.10.3.tar.gz to /home/oracle/.ansible/tmp/ansible-local-519108lfh458k/tmpikc963ue/containers-podman-1.10.3-aqgw3x1r
Installing 'containers.podman:1.10.3' to '/home/oracle/.ansible/collections/ansible_collections/containers/podman'
containers.podman:1.10.3 was installed successfully

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"

Create the Playbook

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.

Install Podman

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.

From a terminal on the ol-server system:

Change to the top level of the working directory, if not still in that directory.
```
cd ~/podman-project
```
Create the playbook file.
```
vi podman-playbook.yml
```
Enter vi insert mode by typing i.
Add the following to the playbook file.
Example:
```
---
- hosts: localhost
  connection: local
  collections:
    - containers.podman
  tasks:

  - name: install podman
    ansible.builtin.dnf:
      name: '@container-tools:ol8'
      state: present
    become: yes
```
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.
Save and close the file. If using vi, you can do that by typing ESC, :wq!, and ENTER.

Run the playbook

ansible-playbook podman-playbook.yml

The command should run successfully with results similar to those shown.

Example output:

[WARNING]: provided hosts list is empty, only localhost is available. Note that
the implicit localhost does not match 'all'

PLAY [localhost] ***************************************************************

TASK [Gathering Facts] *********************************************************
ok: [localhost]

TASK [install podman] **********************************************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Verify the Podman package installed

podman --version

Example output:

[oracle@ol-server podman-project]$ podman --version
podman version 4.4.1

Pull an Image

Once Podman has been installed, 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 .

Edit the playbook file.
```
vi podman-playbook.yml
```
Enter vi insert mode by typing i.
Add the following task to the end of the playbook file.
Ensure to leave a blank line between tasks for readability and follow YAML syntax rules and alignment.
Example:
```
  - name: pull oraclelinux:8 from GitHub
    podman_image:
      name: ghcr.io/oracle/oraclelinux:8
```
Save and close the file. If using vi, you can do that by typing ESC, :wq!, and ENTER.

Run the playbook

ansible-playbook podman-playbook.yml

The command should run successfully with results similar to those shown.

Example output:

[WARNING]: provided hosts list is empty, only localhost is available. Note that
the implicit localhost does not match 'all'

PLAY [localhost] ***************************************************************

TASK [Gathering Facts] *********************************************************
ok: [localhost]

TASK [install podman] **********************************************************
ok: [localhost]

TASK [pull oraclelinux:8 from GitHub] ******************************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Verify Podman pulled the image.

podman images

Example output:

[oracle@ol-server podman-project]$ podman images
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. We'll pull and run the Oracle Linux NGINX developer image in this step.

Edit the playbook file.
```
vi podman-playbook.yml
```
Enter vi insert mode by typing i.
Add the following task to the end of the playbook file.
Ensure to leave a blank line between tasks for readability and follow YAML syntax rules and alignment.
Example:
```
  - 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'
```
The information below will explain a few items further.
- 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.
Save and close the file. If using vi, you can do that by typing ESC, :wq!, and ENTER.

Run the playbook

ansible-playbook podman-playbook.yml

The command should run successfully with results similar to those shown.

Example output:

[WARNING]: provided hosts list is empty, only localhost is available. Note that
the implicit localhost does not match 'all'

PLAY [localhost] ***************************************************************

TASK [Gathering Facts] *********************************************************
ok: [localhost]

TASK [install podman] **********************************************************
ok: [localhost]

TASK [pull oraclelinux:8 from GitHub] ******************************************
ok: [localhost]

TASK [run image] ***************************************************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=4    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

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...  18 minutes ago  Up 18 minutes ago  0.0.0.0:8080->80/tcp  my-ol8

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

Stop the container.

Using the CONTAINER NAMES from the output above, run:

podman stop <CONTAINER NAMES>

Example output:

[oracle@ol-server podman-project]$ podman stop my-ol8
my-ol8
[oracle@ol-server podman-project]$ podman ps
CONTAINER ID  IMAGE       COMMAND     CREATED     STATUS      PORTS       NAMES

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.

Edit the playbook file.
```
vi podman-playbook.yml
```
Enter vi insert mode by typing i.

Create the local directory.

We can efficiently and manually perform this step one time from the command line, but let's automate it. Automating this step ensures the directory exists anytime the playbook runs.

Before the run image task, add these tasks, which create a directory and the index.html file.

Ensure to leave a blank line between tasks for readability and follow YAML syntax rules and alignment.

Example:

  - 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.

Then add the following option at the end of the run image task.
Example:
```
      volume: "/home/oracle/nginx:/usr/share/nginx/html:Z"
```
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
```
http://api-v1:3000/api/v1/labs/6154cf89-6a6e-45b3-98ad-635979b953e8/gitlab/tutorial/files/podman-playbook.yml
```
is a completed version of the playbook for reference.
Save and close the file. If using vi, you can do that by typing ESC, :wq!, and ENTER.

Run the playbook

ansible-playbook podman-playbook.yml

The command should run successfully with results similar to those shown.

Example output:

[WARNING]: provided hosts list is empty, only localhost is available. Note that
the implicit localhost does not match 'all'

PLAY [localhost] ***************************************************************

TASK [Gathering Facts] *********************************************************
ok: [localhost]

TASK [install podman] **********************************************************
ok: [localhost]

TASK [pull oraclelinux:8 from GitHub] ******************************************
ok: [localhost]

TASK [ensure dest directory exists] ********************************************
changed: [localhost]

TASK [create empty file] *******************************************************
changed: [localhost]

TASK [create index.html] *******************************************************
changed: [localhost]

TASK [run image] ***************************************************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=7    changed=4    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

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.
```
curl localhost:8080
```
Where 8080 is the local port mapping to port 80 in the container.
Example output:
```
[oracle@ol-server podman-project]$ curl localhost:8080
Hello! Welcome to Oracle Linux Containers.
```

Summary

The curl output shows a successful connection to the NGINX web server running in the podman container, which we deploy locally using Oracle Linux Automation Engine.

For More Information

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