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.

Objectives

In this tutorial, 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.yml

Update the Oracle Linux instance configuration.

cat << EOF | tee instances.yml > /dev/null
compute_instances:
  1:
    instance_name: "olam-node"
    type: "control"
EOF

Deploy the lab environment.
```
ansible-playbook create_instance.yml -e ansible_python_interpreter="/usr/bin/python3.6" -e "@instances.yml" -e olam_single_host=true
```
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.
The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.
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.

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 tutorial 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 tutorial, 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 set up 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 tutorial 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: "Demo 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 (2.2)"
      scm_type: "git"
      scm_update_on_launch: false
      scm_url: https://github.com/oracle-devrel/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.

Next Steps

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.

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