Note:
- This tutorial is available in an Oracle-provided free lab environment.
- It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.
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.
Login to the WebUI
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 theProceed to localhost (unsafe)
link. -
Login to Oracle Linux Automation Manager with the Username
admin
and the Passwordadmin
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 theEdit
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 theDefault
organization’s details page. -
The
Default
organization’s access page shows theadmin
user. After installation, theadmin
user is the only user in Oracle Linux Automation Manager and is part of theDefault
organization. -
From this page, you can add a new user by clicking the
Add
button or view theadmin
user details by clicking theadmin
user name. -
View the
admin
user by clicking theadmin
user’s name.Clicking this item displays the user details page.
-
Click the
Edit
button to show theEdit 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 oneSystem Administrator
. Changing theadmin
user type without having another user with theSystem 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 aNo 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 theCredential Type
list of values.The
Create New Credential
page expands to allow entering the information for the specific hosts or machines.Enter a
Username
oforacle
and browse for theSSH Private Key
. Clicking theBrowse...
button displays anOpen File
dialog window.Select
Home
in theOpen File
dialog menu.Right-click on the main window of the dialog and then select
Show Hidden Files
.Then select the
.ssh
folder and theid_rsa
file. Clicking theSelect
button causes the contents of the private key file to copy into theSSH Private Key
dialog box. Scroll down and click theSave
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.
-
Set the default branch name used when initializing a project.
git config --global init.defaultBranch main
-
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"
-
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
andhello-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 bothfetch
andpush
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 theCredential Type
list of values. -
The page expands, showing the
Type Details
. -
Enter a
Username
ofgit
and select theSCM Private Key
.In the free lab environment, the
SCM Private Key
is the sameid_rsa
ssh private key used previously for theoracle
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 theOLAM EE (latest)
radio button. -
Click the
Select
button to close the dialog box. -
Select
Git
from theSource Control Credential Type
list of values.The
Create New Project
page expands to show theType 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 theSource 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 mainTemplates
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 theHello 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.
Summary
This welcome message confirms you have a working Oracle Linux Automation Manager installation.
For More Information
Oracle Linux Automation Manager Documentation
Oracle Linux Automation Manager Training
Oracle Linux Training Station
More Learning Resources
Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.
For product documentation, visit Oracle Help Center.
Get Started with Oracle Linux Automation Manager
F74579-02
April 2023
Copyright © 2022, Oracle and/or its affiliates.