Get Started with Oracle Linux Automation Manager

Introduction

Oracle Linux Automation Manager provides features allowing your organization to effectively manage infrastructure configuration through a browser-based user interface.

By the end of this tutorial, you'll have a working Oracle Linux Automation Manager installation ready to run more complex playbooks.

Objectives

In this lab, you'll learn how to:

Use the WebUI
Review the Default Organization
Add a User
Setup an Inventory
Setup a Credential
Create a Project
Setup a Job Template
Run the Job

Prerequisites

A system with Oracle Linux Automation Manager installed.
For details on installing Oracle Linux Automation Manager, see the Oracle Linux Automation Manager Installation Guide .

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

Information: The free lab environment deploys a running single-host Oracle Linux Automation Manager. The deployment takes approximately 15 minutes to finish after launch. Therefore, you might want to step away while this runs and promptly return to complete the lab.

Open a terminal and configure an SSH tunnel to the deployed Oracle Linux Automation Manager instance.
```
ssh -L 8444:localhost:443 oracle@<hostname or ip address>
```
In the free lab environment, use the IP address of the ol-node VM as it runs the Oracle Linux Automation Manager deployment.
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.
Login to Oracle Linux Automation Manager with the Username admin and the Password admin created during the automated deployment.
After login, the WebUI displays.

Navigate the WebUI

Oracle Linux Automation Manager's centralized web UI engine allows for securely and efficiently controlling and managing your infrastructure.

The product is based on the open-source Ansible and AWX projects, providing a visual dashboard for role-based access control, inventory management, and scheduling jobs.

Along the left-hand side of the WebUI, there is a navigation menu allowing quick access to Projects, Inventories, Templates, and Jobs.
Click the menu icon at the top of the menu to collapse and hide the menu. Click it again to expand and unhide the menu.
At the bottom of the navigation menu is the Settings menu item.
Select this item to navigate to the Settings page.
The Settings page gives access to alternative Authentication settings and settings for Job, System, and the User Interface.
Click the Dashboard menu item in the navigation menu.
Clicking this menu item returns you to the main dashboard view showing current Job Status, Recently Used Templates, and Recent Job Runs.
Note: The list of recent items only appears after using templates or running jobs.

Review the Default Organization

Organizations sit at the top of the role-based pyramid and are a logical collection of users, teams, projects, and inventories.

In the navigation menu, click Organizations.
The main window displays a list of the available organizations.
Oracle Linux Automation Manager automatically creates a Default organization available to all users.
View the Default organization by clicking the organization's name.
For the purposes of this lab, we'll use the Default organization as is.
(Optional) If needing to make changes to the Default organization, click the Edit button.
Make any desired changes and then click the Save button.

Administrators needing information about creating new organizations should see the Oracle Linux Automation Manager Users Guide .

Add a User

The WebUI navigation menu Access section manages the default user administration of Oracle Linux Automation Manager. The user administration is role-based and consists of a combination of Organizations, Users, and Teams. Adding users is possible from the Users navigation menu item or directly from within an organization.

Find an Organization's Users

Click the Access tab on the Default organization's details page.
The Default organization's access page shows the admin user. After installation, the admin user is the only user in Oracle Linux Automation Manager and is part of the Default organization.
From this page, you can add a new user by clicking the Add button or view the admin user details by clicking the admin user name.
View the admin user by clicking the admin user's name.
Clicking this item displays the user details page.
Click the Edit button to show the Edit Details page.
This page allows editing the user's email, password, role, and other details.
Important: Do not change the admin user's type (role). Oracle Linux Automation Manager requires at least one System Administrator. Changing the admin user type without having another user with the System Administrator role will lock you out of administrating Oracle Linux Automation Manager.
Click Cancel.

Add a User

In the navigation menu, click Users.
The main window displays a list of available users.
Click the Add button to create a new user.
Add the required details on the Create New User page.
Click the Save button.
The new user details page displays.

Setup an Inventory

An inventory is a group of hosts managed by Oracle Linux Automation Manager. Users leverage an inventory to automate host orchestration by running playbooks.

View the current list of inventories by clicking the Inventories navigation menu item.
The main window shows the message No Inventories Found on a new installation.
Add a new inventory by clicking the Add button.
Select Add Inventory from the drop-down menu.
Add the requested details to the Create new inventory page.
Click the Save button when finished.
The new inventory details page displays.
Click the Hosts tab from the inventory details page.
The page displays a list of hosts that are associated with the inventory. The message No Hosts Found appears on a newly created inventory until adding the first host.
Click the Add button.
The Create new host page displays.
Enter a hostname or IP address for a host in the Name text field.
When using hostnames, they must be resolvable on the network where the Oracle Linux Automation Manager resides.
For the free lab environment, enter the public IP address of the git-server from the Luna Lab Resources page. This server is an additional Oracle Linux instance that deploys with the free lab environment.
Click the Save button.
The main window displays the Host details page and summarizes information about the newly created host we added to the inventory.

Setup a Credential

Credentials authenticate a user within Oracle Linux Automation Manager against machines using passwords and SSH keys, sync inventory sources, and import playbooks from version control systems such as GitHub. Each credential may contain usernames, passwords, private keys, or other security-related information.

Navigate within the menu and click Credentials.
The Credentials page displays a No Items Found message on a newly installed system.
Click the Add button.
The Create New Credential page displays.
Enter the requested information.
Select the Machine credential type in the Credential Type list of values.
The Create New Credential page expands to allow entering the information for the specific hosts or machines.
Enter a Username of oracle and browse for the SSH Private Key. Clicking the Browse... button displays an Open File dialog window.
Select Home in the Open File dialog menu.
Right-click on the main window of the dialog and then select Show Hidden Files.
Then select the .ssh folder and the id_rsa file. Clicking the Select button causes the contents of the private key file to copy into the SSH Private Key dialog box. Scroll down and click the Save button.
The main window updates to show the credential Details page.
This page provides a summary of the newly created credential.

Create a Project

A Project is a compilation of playbooks grouped based on their actions or the hosts with which they interact.

We have multiple ways to manage these playbooks using Oracle Linux Automation Manager, such as manually or using a git-based source control management (SCM) solution such as GitHub or Gitlab.

Use Source Control

While Oracle Linux Automation Manager allows storing playbooks locally on the same server, storing them within a supported source control server such as Git is best practice.

To help, Oracle provides a collection of ansible playbooks on GitHub for use with Oracle Linux Automation Manager or Oracle Linux Automation Engine.

But what if you only needed a single playbook or wanted to customize a playbook to your environment?

That is where having your self-hosted Git server or personal online repository such as GitHub comes in handy.

For this tutorial, the free lab environment deploys a standalone Git server to the git-server VM.

Open a new terminal.
Note: In the free lab environment, do not ssh to a server for this step, as we'll directly use the provided Luna desktop.
Clone the Oracle Samples Anisble Collections repository.
```
git clone https://github.com/oracle-samples/ansible-collections.git
```
Cloning the repository creates the ansible-collections directory in the Luna Users home directory containing the requested repository contents.
Create a new local project directory.
```
mkdir hello-world
```
Change into the new project's working directory.
```
cd hello-world
```

Create a README file for the new project.

echo "# First sample project" > README.md

Add a sample playbook.
Copy the hello-world.yml playbook from the Oracle Samples Ansible Collection repository into the new project.
```
cp ../ansible-collections/playbooks/OL_Admin/hello-world.yml .
```
Initialize the project's working directory into a Git repository.
Before initializing the repository, you need to perform some Git first-time setup steps.
1. Set the default branch name used when initializing a project.
```
git config --global init.defaultBranch main
```
2. Set your Identity.
  Note: The email and name below are examples within this tutorial. Using your actual email and name outside this tutorial is essential, and this information gets immutably baked into each of your commits.
```
git config --global user.email johndoe@example.com
git config --global user.name "John Doe"
```
3. Initialize the directory as a local Git repository.
```
git init
```
  The command returns that it Initialized the empty Git repository.
Check the state of the working directory and project staging area.
```
git status
```
The state of the local repository indicates two untracked files, README.md and hello-world.yml.
Add and track the new files in the staging area.
```
git add --all
```
The --all option adds all untracked and changed files to the staging area.
Commit the changes currently in the staging area.
```
git commit -m 'initial commit'
```
The -m option allows adding a comment to the committed changes.

Create and initialize the remote Git repository.

A remote is a shared repository used by all project contributors and stored on a code-hosting service like GitHub or a self-hosted server.

ssh git@<hostname or ip address of Git server> "git init --bare /git-server/repos/hello-world.git"

Use the public IP address shown for the git-server VM on the free lab environment's Luna Lab Resources page.

Accept the ECDSA key fingerprint to continue.

Example Output:

[luna.user@lunabox hello-world]$ ssh git@130.61.79.231 "git init --bare /git-server/repos/hello-world.git"
The authenticity of host '130.61.79.231 (130.61.79.231)' can't be established.
ECDSA key fingerprint is SHA256:EBdUMoRul8Yd8SP8dI003NE8SXdbsHvhILAtsw9YNf0.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '130.61.79.231' (ECDSA) to the list of known hosts.
Initialized empty Git repository in /git-server/repos/hello-world.git/

Add the new remote repository connection record.
After adding the remote to the local repository, you can use it as a shortcut in other Git commands.
```
git remote add origin git@<hostname or ip address of Git server>:/git-server/repos/hello-world.git
```
The IP address is the address of the remote Git server, and the path after the colon is the repository's location on the remote Git server.

Verify the newly added connection record.

git remote -v

Example Output:

[luna.user@lunabox hello-world]$ git remote -v
origin	 git@130.61.79.231:/git-server/repos/hello-world.git (fetch)
origin	 git@130.61.79.231:/git-server/repos/hello-world.git (push)

The output shows the connection record origin pointing to the remote Git repository location for both fetch and push Git commands.

Push local repository changes to the remote repository.

git push origin main

Example Output

[luna.user@lunabox hello-world]$ git push origin main
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 4 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 586 bytes | 586.00 KiB/s, done.
Total 4 (delta 0), reused 0 (delta 0), pack-reused 0
To 130.61.79.231:/git-server/repos/hello-world.git
 * [new branch]      main -> main

With the hello-world.yml sample code available on the remote Git repository, it is possible to use it in an Oracle Linux Automation Manager Project.

Add Source Control Credential

Before creating a project, we need to add the credentials for the Git server to Oracle Linux Automation Manager. These credentials allow Oracle Linux Automation Manager to pull the project securely over an ssh connection as the git user.

This step is unnecessary for a public repository where the project is available without authentication over the HTTPS protocol.

Open the browser tab or window logged into Oracle Linux Automation Manager.
Navigate and click on Credentials in the navigation menu.
Click the Add button to add a new credential.
Enter the required information and select Source Control from the Credential Type list of values.
The page expands, showing the Type Details.
Enter a Username of git and select the SCM Private Key.
In the free lab environment, the SCM Private Key is the same id_rsa ssh private key used previously for the oracle user.
Scroll down the page and click the Save button.

Create a Project

Click Projects in the navigation menu.
Then click the Add button.
Enter the requested information on the Create New Project page.
Click the search icon next to the Execution Environment list of values.
In the Select Execution Environment pop-up dialog box, click the OLAM EE (latest) radio button.
Click the Select button to close the dialog box.
Select Git from the Source Control Credential Type list of values.
The Create New Project page expands to show the Type Details.
Enter the Source Control URL value into the text field.
```
git@<hostname or ip address of Git server>:/git-server/repos/hello-world.git
```
You can click the more information icon next to this field to see sample values. This tutorial uses the same values displayed in the terminal output when running git remote -v.
Enter the Source Control Credential by clicking the search icon and selecting the credential corresponding to the Source Control URL.
Review each of the additional Options.
Clicking on the more information icon next to each option provides details on its functionality.
Click the Save button.
The main window displays a project summary on a Details page.
If the project can properly communicate with the Git server and pull the project, a Successful job status appears within the summary details.

Setup a Job Template

A Job Template consists of all the parts and pieces required to run a playbook and represents the ansible-playbook command provided in the Oracle Linux Automation Engine.

From the navigation menu, click Templates.
Click the Add button on the main Templates page.
Select Add job template from the displayed list of values.
Enter the requested information on the Create New Job Template page.
Scroll to the bottom, and click the Save button.
The Detail summary page displays the new template.

Run the Job

With the template creation complete, we can now run the playbook.

Using the breadcrumbs navigation at the top of the page, click Templates.
This click returns you to the Templates overview page.
Use the rocket icon under the Actions column and launch the Hello Template job template.
After launch, a status page displays the job output and, eventually, the results.
The playbook prints a welcome message to the screen if it runs successfully.