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 tutorial, 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 to another using a passwordless SSH login

Deploy Oracle Linux

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"
  2:
    instance_name: "ol-host"
    type: "remote"
olam_type: none
EOF

Create an inventory file.

cat << EOF | tee hosts > /dev/null
localhost ansible_connection=local ansible_connection=local ansible_python_interpreter=/usr/bin/python3.6
EOF

Deploy the lab environment.
```
ansible-playbook create_instance.yml -i hosts -e "@instances.yml"
```
The free lab environment requires the extra variable ansible_python_interpreter for localhost because it installs the RPM package for the Oracle Cloud Infrastructure SDK for Python. The location for installing this package is under the system's default Python modules based on your version of Oracle Linux. Using an inventory variable avoids impacting the plays running on hosts other than localhost.
The default deployment shape uses the AMD CPU. You can change the shape of the instances by passing a new shape variable definition on the command line.
For example: -e instance_shape="VM.Standard3.Flex"
Similarly, the default version of the Oracle Linux image uses the variable os_version defined in the `default_vars.yml file. You can modify this value by passing the Oracle Linux major version on the command line.
For example: -e os_version="9"
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. Note the previous play, which prints the public and private IP addresses of the nodes it deploys.

Setup Oracle Linux Automation Engine Control Node

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.

Set a variable equal to the control node's IP address.
```
export CONTROL="<ip_address_of_ol-control-node>"
```
Open a terminal and copy the SSH key pair to the control node.
```
scp -rp ~/.ssh/id_rsa* oracle@$CONTROL:~/.ssh/
```

Set the permissions on the SSH private key.

ssh oracle@$CONTROL "chmod 600 ~/.ssh/id_rsa"

Connect to the ol-control-node system via SSH.
```
ssh oracle@$CONTROL
```
Install the Oracle Linux Automation Engine package and dependencies.
```
sudo dnf install -y ansible-core
```
The ansible-core package is available in the AppStream repository of Oracle Linux.
Test the package installation.
```
ansible --version
```
The output will display the command version, configuration details, and Python version dependency.
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 that 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 to gather this information can vary depending on the type of system and the location of the deployment.

In the provided free lab environment, we need the IP address of the ol-host system, which the deployment script displays as part of its output.

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 preferred text editor. 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.
Example:
```
130.61.100.96
```
Save and close the file. If using vi, you can type ESC, :wq! and ENTER.

Validate the inventory file.

ansible-inventory -i inventory --list

The output shows the inventory information.

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, followed by the IP address below it.
Example:
```
[development]
130.61.100.96
```
Save and close the file. If using vi, you can type ESC, :wq! and ENTER.

Run the validate step again and verify that the output contains the group.

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 created inventory file. This sample playbook consists 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 indicates that you'll run the playbook against every host listed in the inventory. Alternatively, you can instruct a playbook to run tasks only against a specific list of hosts or groups by listing each target, separated by colons or commas. The task then uses the debug module to print a message.
The name line causes Oracle Linux Automation Engine to display output in the terminal as it 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

If everything works, the command completes successfully and prints 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 from 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 a list of facts for the host.
```
ansible ol-host -i inventory -m setup
```

Next Steps

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