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 in Release 1.0, Oracle Linux Automation Engine now stems from the open-source ansible-core
software package as of Release 2.0.
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:
- latest Oracle Linux 8 (x86_64)
- 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 theol8_appstream
repository as of Oracle Linux 8 Update 6.Test the package installation.
ansible --version
The output will display the commands version, configuration details, and python version dependency.
Example output:
ansible [core 2.13.3] 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.9/site-packages/ansible ansible collection location = /home/oracle/.ansible/collections:/usr/share/ansible/collections executable location = /usr/bin/ansible python version = 3.9.13 (main, Nov 16 2022, 15:11:16) [GCC 8.5.0 20210514 (Red Hat 8.5.0-15.0.1)] jinja version = 3.1.2 libyaml = True
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
cd ~
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 typingi
.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 typingESC
,:wq!
andENTER
.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 theungrouped
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 typingi
.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 typingESC
,:wq!
andENTER
.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 variableansible_user
. While in the inventory file, give the host a hostname reference and assign the IP address to the variableansible_host
.Add the remote user to the inventory file.
vi inventory
Enter
vi
insert mode by typingi
.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 ofol-host
for the hostname.Save and close the file. If using
vi
, you can do that by typingESC
,:wq!
andENTER
.Rerun the
ping
module, using the hostname rather thanall
.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 typingi
.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 ahosts
line specifying which hosts to manage. Theall
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 typingESC
,:wq!
andENTER
.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