Write a Playbook with Oracle Linux Automation Engine

Introduction

The Oracle Linux Automation Engine, a component of Oracle Linux Automation Manager, is an automation tool for deploying software, configuring systems, and orchestrating tasks, such as upgrades and updates, in the form of playbooks. Initially using the ansible package, Oracle Linux Automation Engine now stems from the open-source ansible-core software package.

The following tutorial introduces writing playbooks with Oracle Linux Automation Engine.

Objectives

In this lab, you'll learn how to:

Install Oracle Linux Automation Engine
Create an inventory file
Run an ad hoc command
Write and run a playbook

Prerequisites

A minimum of two Oracle Linux systems with the following configuration:
- a non-root user with sudo permissions
- ssh keypair for the non-root user
- the ability to ssh from one host (control-node) to the other (host) using passwordless ssh login

Setup Oracle Linux Automation Engine Control Node

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

The control node is the system for running the Oracle Linux Automation Engine playbooks. Running playbooks requires the installation of the Oracle Linux Automation Engine package.

If not already connected, open a terminal and connect via ssh to the ol-control-node system.
```
ssh oracle@<ip_address_of_ol-control-node>
```
Install the Oracle Linux Automation Engine package and dependencies.
```
sudo dnf install -y ansible-core
```
The ansible-core package is available in the ol8_appstream repository as of Oracle Linux

Test the package installation.

ansible --version

The output will display the commands version, configuration details, and python version dependency.

Example output:

[oracle@ol-control-node ~]$ ansible --version
ansible [core 2.14.2]
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/oracle/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.11/site-packages/ansible
  ansible collection location = /home/oracle/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/bin/ansible
  python version = 3.11.2 (main, Jun 14 2023, 13:00:29) [GCC 8.5.0 20210514 (Red Hat 8.5.0-18.0.2)] (/usr/bin/python3.11)
  jinja version = 3.1.2
  libyaml = True

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 an Inventory

The inventory file contains details about the hosts that belong to your infrastructure or you'll manage using Oracle Linux Automation Engine. These details instruct how to connect to these hosts when running ad hoc commands or playbooks.

Gather IP Address or Hostname Information

To create an inventory for Oracle Linux Automation Engine, you'll need to determine the IP address or resolvable hostname of the system or systems you manage. The steps can vary based on the type of system and where you are deploying it.

In the provided free lab environment, we need the IP address of the ol-host system, which we locate using the Luna Lab Resources tab.

Create Inventory File

The Oracle Linux Automation Engine places the default inventory in /etc/ansible/hosts. It also allows a project-level inventory file. When using a project-level inventory, you'll need to provide the path to the inventory file using the -i option when running ad hoc commands or playbooks.

From a terminal on the Oracle Linux Automation Engine Control Node:

Create a project directory
```
mkdir ~/ol-automation
```
Move to the new directory and open a new inventory file using your text editor of choice. Here, we'll use vi.
```
cd ~/ol-automation
```
```
vi inventory
```
Enter vi insert mode by typing i.
Add the public IP address of the provided ol-host system. The file should only contain the IP address, as shown in the example.
Example:
```
130.61.100.96
```
Save and close the file. If using vi, you can do that by typing ESC, :wq! and ENTER.

Validate the inventory file.

ansible-inventory -i inventory --list

The output shows the information about the inventory.

Example output:

{
    "_meta": {
        "hostvars": {}
    },
    "all": {
        "children": [
            "ungrouped"
        ]
    },
    "ungrouped": {
        "hosts": [
            "130.61.100.96"
        ]
    }
}

The reference all refers to every host in the inventory file, and the ungrouped section is for any hosts not part of a listed group.

Edit the inventory and place the host within a group called development.
```
vi inventory
```
Enter vi insert mode by typing i.
Add the group name within brackets with the IP address below, as shown in the example.
Example:
```
[development]
130.61.100.96
```
Save and close the file. If using vi, you can do that by typing ESC, :wq! and ENTER.

Run the validate step again to see the group added to the output.

ansible-inventory -i inventory --list

The output shows the updated information with the group.

Example output:

{
    "_meta": {
        "hostvars": {}
    },
    "all": {
        "children": [
            "development",
            "ungrouped"
        ]
    },
    "development": {
        "hosts": [
            "130.61.100.96"
        ]
    }
}

Run Ad Hoc Command

Oracle Linux Automation Engine has several run-once modules that don't require writing a playbook. The most basic of those is the ping module, which attempts to make an SSH connection based on the details provided in the inventory.

From a terminal on the Oracle Linux Automation Engine Control Node:

Run the ping module.
```
ansible all -i inventory -m ping
```
The all option instructs the command to run against all the hosts listed in the inventory file specified by the -i option. The command also accepts individual hostnames or groups.
The -m option specifies the module to run.
Accept the ECDSA key fingerprint by typing yes at the prompt.
Based on your environment, the ping might fail with the following output:
Example output:
```
130.61.100.96 | UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: Warning: Permanently added '130.61.100.96' (ECDSA) to the list of known hosts.\r\noracle@130.61.100.96: Permission denied (publickey,gssapi-keyex,gssapi-with-mic).",
    "unreachable": true
}
```
This failure occurs because the local user account oracle does not exist on the host we're trying to manage. Fix this by adding a valid remote user into the inventory using the variable ansible_user. While in the inventory file, give the host a hostname reference and assign the IP address to the variable ansible_host.
Add the remote user to the inventory file.
```
vi inventory
```
Enter vi insert mode by typing i.
Add the two variables as shown in the example.
Example:
```
[development]
ol-host ansible_host=130.61.100.96 ansible_user=opc
```
The free lab environment provides a pre-configured system for testing remote management containing a user named opc. opc is the default user created on an Oracle Linux instance in Oracle Cloud Infrastructure (OCI). We can use a sample name of ol-host for the hostname.
Save and close the file. If using vi, you can do that by typing ESC, :wq! and ENTER.

Rerun the ping module, using the hostname rather than all.

ansible ol-host -i inventory -m ping

The command runs successfully with results similar to those shown.

Example output:

ol-host | SUCCESS => {
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python"
    },
    "changed": false,
    "ping": "pong"
}

Write a Playbook

A playbook is a set of instructions, written in proper YAML syntax, run against a single host or a group of hosts. These files have the default extension of .yml, or .yaml.

Our first playbook will target all hosts from the provided inventory file. The contents of this sample playbook consist of a single task that prints a debug message.

From a terminal on the Oracle Linux Automation Engine Control Node:

Create a new playbook file.
```
vi hello.yml
```
Enter vi insert mode by typing i.
Add the following text to the playbook file.
Example:
```
---
- hosts: all
  tasks:
    - name: Print message
      debug:
        msg: Hello from Oracle Linux
```
A playbook should always start with ---, followed by a hosts line specifying which hosts to manage. The all value states the playbook will act upon every host listed in the inventory. Alternatively, you can instruct a playbook to only run tasks against a specific list of hosts or groups by listing each separated by colons or commas. The task then uses the debug module to print a message.
The name line provides an output for each of your plays and tasks as Oracle Linux Automation Engine runs the playbook.
Save and close the file. If using vi, you can do that by typing ESC, :wq! and ENTER.

Run the hello.yml playbook against the inventory.

ansible-playbook -i inventory hello.yml

Rather than using the variable ansible_user in the inventory file, you can instead pass the remote username on the command line using the option -u username.
ansible-playbook -i inventory hello.yml -u opc

The command should complete successfully and print out the debug message.

Example output:


PLAY [all] *********************************************************************

TASK [Gathering Facts] *********************************************************
[WARNING]: Platform linux on host ol-host is using the discovered Python
interpreter at /usr/bin/python, but future installation of another Python
interpreter could change this. See https://docs.ansible.com/ansible/2.9/referen
ce_appendices/interpreter_discovery.html for more information.
ok: [ol-host]

TASK [Print message] ***********************************************************
ok: [ol-host] => {
    "msg": "Hello Oracle Linux"
}

PLAY RECAP *********************************************************************
ol-host                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

As the inventory only defines a single host, ol-host, the playbook runs once. Before running the task listed in the playbook, Oracle Linux Automation Engine runs a default task gathering information called facts. This task pulls information about the remote host, which playbooks may later utilize to customize task behavior through conditionals.

Run the following ad hoc command to print out a full list of facts for the host.
```
ansible ol-host -i inventory -m setup
```

Summary

This message and facts output confirm you have run your first playbook successfully using Oracle Linux Automation Engine.

For More Information

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