Manage Oracle Linux Automation Manager Using the AWX Collection

Introduction

The AWX Ansible Collection allows administrators to interact with Oracle Linux Automation Manager through playbooks. The modules include the ability to perform tasks such as user and group administration, creating projects, and running jobs.

This tutorial provides details on how to deploy a DevOps instance for running the playbooks and another instance with the installation of Oracle Linux Automation Manager.

Objectives

In this lab, you'll learn how to:

Deploy the DevOps and Oracle Linux Automation Manager instances
Setup the config file on the DevOps instance
Write a playbook to create the required items to run a Job
Test and verify the playbook

Prerequisites

A control node for running Oracle Linux Automation Engine playbooks
An instance of Oracle Linux Automation Manager

Deploy Oracle Linux Automation Manager

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

Deploy the lab environment.
```
ansible-playbook create_instance.yaml -e ansible_python_interpreter="/usr/bin/python3.6"
```
The free lab environment requires the extra variable ansible_python_interpreter because it installs the RPM package for the Oracle Cloud Infrastructure SDK for Python. The location for this package's installation is under the python3.6 modules.
Important: Wait for the playbook to run successfully and reach the pause task. The Oracle Linux Automation Manager installation is complete at this stage of the playbook, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys.
Note: We'll use the Luna Desktop as the control node for running our playbooks in the free lab environment rather than the one from the deployment.

Verify Deployment of Oracle Linux Automation Manager

Open a new terminal.
Configure an SSH tunnel to the Oracle Linux Automation Manager instance.
```
ssh -o ExitOnForwardFailure=yes -f -L 8444:localhost:443 oracle@<public_ip_address_of_olam-node> sleep 300
```
- -o ExitOnForwardFailure=yes: waits for all remote port forwards to establish successfully
- -f: runs the SSH tunnel in the background
- -L: creates the tunnel on port 8444 on the local system and 443 on the remote system
- sleep 300: keeps remote tunnel open for 5 minutes, waiting for an established connection before automatically closing
Open a web browser and enter the URL.
```
https://localhost:8444
```
Note: Approve the security warning based on the browser used. For Chrome, click the Advanced button and then the Proceed to localhost (unsafe) link.
Log in to Oracle Linux Automation Manager with the Username admin and the Password admin created during deployment.
After logging in, the WebUI displays.

Create the Controller Configuration File

The AWX Ansible Collection uses a configuration file and sometimes the AWX CLI to authenticate against Oracle Linux Automation Manager. The authentication parameters can be passed on the command line using the CLI directly or written to a configuration file.

When specifying the authentication parameters, the AWX Ansible Collection expects a combination of either:

host, username, password
host, OAuth2 token

More details are available in the upsteam project.

Return to the terminal where you created the SSH tunnel.
Generate the configuration file.
```
cat << EOF | tee ~/.tower_cli.cfg > /dev/null
[general]
host: https://localhost:8444
verify_ssl: false
username: admin
password: admin
use_token = false
EOF
```
- host: - defines the URL to access the Oracle Linux Automation Manager WebUI
- verify_ssl: - turns off strict SSL checking since the lab environment uses a self-signed certificate
- use_token: - although using an OAuth2 token is preferred, setting to false turns off using one for authentication

Create an Organization

As we cover in our Get Started lab, an Organization sits at the top of the role-based pyramid and is a logical collection of users, teams, projects, and inventories.

Rather than creating this through the WebUI, we can write a playbook.

Write the playbook.

cat << EOF | tee configure-olam.yaml > /dev/null
---
- name: Playbook to setup training demo data using the AWX collection
  hosts: localhost
  gather_facts: false
  collections:
    - awx.awx

  tasks:

  - name: Create an organization
    awx.awx.organization:
      name: "Example"
      description: "Created using a playbook"
      state: present

EOF

Run the playbook.
```
ansible-playbook configure-olam.yaml
```
Verify the changes in the WebUI.
Using the browser, log in to the WebUI.
Note: If you get a failure on login, it is possible that the SSH tunnel has expired, and you'll want to rerun the SSH command to reestablish the connection.
In the navigation menu, click Organizations. Notice the Example entry, which the playbook created.

Run a Job

With the Organization created, now let's automate the remaining steps in the Get Started lab with a few modifications. One of the benefits of Oracle Linux Automation Engine is its self-documenting.

Return to the terminal where you created the playbook.

Append the additional configuration to the existing playbook.

cat << EOF | tee -a configure-olam.yaml > /dev/null
  - name: Add a user
    awx.awx.user:
      username: jdoe
      password: oracle
      email: jdoe@example.com
      first_name: John
      last_name: Doe
      organization: Example
      state: present

  - name: Add an inventory
    awx.awx.inventory:
      name: "Demo Inventory"
      description: "Lab OCI Instances"
      organization: Example
      state: present
   
  - name: Add a host
    awx.awx.host:
      name: localhost
      description: "Use to run tasks locally"
      inventory: "Demo Inventory"
      state: present
      variables:
        ansible_connection: local

  - name: Add a credential
    awx.awx.credential:
      name: "Linux Instance"
      credential_type: Machine
      organization: Example
      inputs:
        username: opc
        ssh_key_data: "{{ lookup('file', '~/.ssh/id_rsa') }}"

  - name: Add a project
    awx.awx.project:
      name: "Hello World"
      description: "Sample Hello World Project"
      organization: Example
      default_environment: "OLAM EE (latest)"
      scm_type: "git"
      scm_update_on_launch: false
      scm_url: https://github.com/bgraef/linux-virt-labs.git
      state: present

  - name: Add a template
    awx.awx.job_template:
      name: "Say Hello"
      job_type: "run"
      organization: Example
      inventory: "Demo Inventory"
      project: "Hello World"
      playbook: "labs/olam-hello-world.yaml"
      state: present

  - name: Launch a job
    awx.awx.job_launch:
      job_template: "Say Hello"
      wait: true
    register: job

  - name: Print results from job
    ansible.builtin.debug:
      var: job
         
EOF

Rerun the playbook.
```
ansible-playbook configure-olam.yaml
```
The playbook finishes with the last play showing the status of the job as successful, and a warning which we can ignore.
Verify the Job in the WebUI.
Using the browser, navigate to Jobs and click the Say Hello job. The output displays the results of the playbook run during the job. Notice the welcome messages from the debug task.

Teardown the Oracle Linux Automation Manager Deployment

With the lab complete, we can now unpause the playbook.

Return to the terminal showing the paused create_instance.yaml playbook.
Click ENTER in the terminal.
This action causes the playbook to continue and finish the remaining tasks, removing the deployed resources in Oracle Cloud Infrastructure. Wait for the playbook to complete, thus ending the lab.

Summary

The output within the WebUI confirms you have a working Oracle Linux Automation Manager and have written a playbook to manage some of the more common tasks.

For More Information

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