3 Managing Resources
This chapter describes managing resources. Resources are the primary configuration touch points between Oracle Linux Automation Manager and playbooks and inventory. These resources are projects, inventories, credentials, job templates, and workflow templates.
Managing Projects
A Project is a resource that represents a repository of Oracle Linux Automation Engine playbooks. The repository can be local or on a remote source code management (SCM) system such as Git.
To create a project, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Projects.
The Projects page appears.
-
Click the Add button.
The Create New Project page appears.
-
In the Name field, enter a name. For example,
Project1
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
If the project has ansible collection requirements, you must ensure you select an organization that lets you use one or more of the following options:
-
Download Collections from Repositories at Runtime
To use this option, you must select an organization that has a credential set up for each repository you need to download collections from. See Setting Up Ansible Galaxy/Automation Hub API Token Credentials for more information.
-
Utilize a Custom Execution Environment Hosted in Private Automation Hub
To use this option, you must select an organization with an execution environment whose Image property references a Private Automation Hub custom execution environment containing ansible collections.
From the organization list, select an organization.
-
-
Click Select.
-
From the Source Control Credential Type list, select one of the following:
-
Manual:
The Manual option lets you select a local playbook on the machine hosting Oracle Linux Automation Manager. You select the playbook from a drop-down list labeled Playbook Directory.
See Accessing a Local Playbook for more information.
-
Git:
The Git options lets you use a playbook from a remote repository. Selecting one of these options displays source control fields for you to complete so that you can access a chosen remote repository.
For example, go to Accessing a Remote Playbook on Git for information about setting up source details and credentials.
- Subversion:
The Subversion options lets you use a playbook from a remote repository. Selecting one of these options displays source control fields for you to complete so that you can access a chosen remote repository.
- Remote Archive:
The Remote Archive options lets you use a playbook from a remote archive. Selecting one of these options displays source control fields for you to complete so that you can access a chosen remote repository.
-
-
Click Save.
Accessing a Local Playbook
To make a local playbook accessible to an instance of Oracle Linux Automation Manager, ensure you have the required administrative privileges and perform the following steps:
- Log onto the server hosting Oracle Linux Automation Manager.
-
Create a directory to store the playbooks. The default location is
/var/lib/ol-automation-manager/projects
.Note:
The Oracle Linux Automation Manager might list the Project Base Path as/var/lib/awx/projects
instead of/var/lib/ol-automation-manager/projects
. Both locations are the same as/var/lib/awx
is a symbolic link to/var/lib/ol-automation-manager
. -
Copy or create playbook files in the directory. For sample playbooks, see
/var/lib/ol-automation-manager/projects/demo_bundled
. -
Set the playbook directory and files to the same user and group and permissions that Oracle Linux Automation Manager uses.
Note:
Check the SELinux permissions and context settings if you have issues adding a project path.
Accessing a Remote Playbook on Git
Git is a distributed version control system containing repositories where you can store playbooks that you can clone to Oracle Linux Automation Manager systems as part of projects.
To access a remote playbook on Git, do the following:
-
Set up a new Git repository or use an existing Git repository on a remote Git server.
For example, GitHub hosts the public Ansible example projects at https://github.com/ansible/ansible-tower-samples.Caution:
As this is a public repository, Oracle isn't responsible for examples contained therein.
-
If you're using a private repository that requires SSH authentication, you must set up SSH private and public keys on the system running Oracle Linux Automation Manager and copy the public key to your Git user account.
- Return to the Oracle Linux Automation Manager UI and from the Resources section, click Projects.
The Projects page appears.
- Click the name of the project you want to change, then click Edit.
- Confirm that the Source Control Type is set to Git, then enter a URL to the SCM repository in the Source Control URL field.
-
If you need to specify an SCM branch, tag, or commit in the Source Control Branch/Tag/Commit field, enter a branch, tags, or commit hash.
-
If you need to retrieve a refspec from a branch, in the Source Control Refspec field, enter a refspec.
-
If the Git repository you specified is private and requires credentials to access, from the Source Control Credential list, select a credential. For more information about setting up credentials, see Setting Up Credentials.
-
Click Save.
-
If Oracle Linux Automation Manager requires access to the Git repository through a proxy, expand the left side menu and click Settings.
The Settings page appears.
-
Click Jobs settings.
The Details page appears.
-
Click the Edit button.
-
In the Extra Environment Variables field, enter the following:
{ "https_proxy": "proxy_address:proxy_port" }
In the previous example, proxy_address is the proxy address and proxy_port is the port for the proxy.
-
Click Save.
Note:
If a playbook uses the OCI Ansible collection, see https://docs.oracle.com/iaas/Content/API/SDKDocs/ansible.htm and find the setup instructions relating to AWX.
Managing Inventories, Groups, and Hosts
The following sections provide information about managing inventories and hosts.
Managing Inventories and Groups
An inventory is a collection of hosts against which jobs and commands can be run. You can create groups within inventories and further subdivide these groups into subgroups.
Creating an inventory
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
From the Resources section, click Inventories.
The Inventories page appears.
-
Click the Add button.
A menu appears.
-
Click the Add Inventory option.
The Create new inventory page appears.
-
In the Name field, enter a name for the inventory. For example,
Inventory1
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the Organization list, select an organization.
-
Click Select.
-
In the Variables field (a code box), you can enter YAML or JSON code to specify any inventory variables by doing the following:
- Click the YAML or the JSON button to specify which syntax to use.
- Type the variables in the code edit box.
-
Click Save.
Adding groups or subgroups to an inventory
- Click Groups.
A list of Groups appears.
- Click Add.
The Create new group dialog appears.
- In the Name field, add a name.
- Click Save.
The Group details page appears.
- Click Related Groups.
The Related Groups page appears.
- Click Add.
- Do one of the following:
- To add an existing group, click Add existing group and choose one or more existing groups to relate to the existing group.
- To add a new group, click Add new group and create a group that is related to the current group.
- Click Save.
Managing Hosts
To create a host, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
From the Resources section, click Hosts.
The Hosts page appears.
-
Click the Add button.
The Create New Host page appears.
-
In the Name field, enter the IP address or host name.
- In the Inventory field click the search button.
The Select Inventory page appears.
-
From the inventory list, select an inventory.
-
Click Save.
The Details page appears.
- Set the host to On or Off to indicate whether the host is available for jobs or not.
- Click Facts to review any facts gathered for the host from jobs run on the host. For more information about enabling fact storage, see Setting Up a Job Template.
- Click Groups.
A list of groups appears, if any are configured.
- Click Add to add a group.
- Select one or more groups from the list to add the host to the group. The groups that can be selected are created in the inventory that the host is associated with. For more information about creating groups, see Managing Inventories and Groups.
- Click Save.
Running One-Off Commands Against a Host or Group
To run single commands using Oracle Linux Automation Engine built-in modules against one or more hosts or group of hosts in an inventory (similar to running a module on the command line), do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
From the Resources section, click Inventories.
The Inventories page appears with a list of available inventories.
- Click the name of the inventory containing the hosts against which you want to run a
command.
The inventory is displayed in the Details Tab.
-
Do one of the following:
-
Click the Hosts tab to run commands on one or more hosts.
- Click the Groups tab to run commands on one or more groups of hosts.
-
-
Select the checkbox beside one or more hosts or groups on the left side.
Note:
If you don't select any of the check boxes the system assumes you want to run the command against all the hosts or groups. -
Click the Run Command button.
The Run Command page appears.
-
From the Modules list, select a module. For example, choose a module shell.
-
In the Arguments field, enter any arguments that are required by the selected module. For example,
uname -a
. -
Click Next.
A list of available execution environments is displayed.
-
Select the Execution Environment.
If you don't select an environment, the command runs in the
OLAM EE
execution environment by default. -
Click Next.
A list of available machine credentials is listed.
-
Select the Machine Credential for the machines. See Setting Up Credentials for information about setting up credentials.
-
Click Launch.
The Output page appears showing the job operations in real-time and eventually displays a status of Success of Failed.
Managing Smart Inventories
A smart inventory is a type of inventory where hosts are automatically grouped based on filter criteria rather than manually defined groups. Host filter criteria can be based on attributes such as host names, group memberships, or based on host facts collected and stored by a previously run job that collected facts about the host. The inventory is updated every time a job runs that uses a smart inventory.
To set up a smart inventory, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
From the Resources section, click Inventories.
The Inventories page appears.
-
Click the Add button.
A menu appears.
-
Click the Add Smart Inventory option.
The Create new smart inventory page appears.
-
In the Name field, enter a name for the smart inventory.
-
In the Organization field, click search.
The Select Organization dialog appears.
-
From the Organization list, select an organization.
-
Click Select.
Note:
You can only create smart inventories using inventories that are part of the same organization. - In the Smart host filter field, click the search icon.
The Perform a search to define a host filter dialog appears.
- To perform a search based on information configured in or generated by Oracle Linux
Automation Manager, select one of the following:
- Name: Enter either the full name of the host or a part of a name that might
be shared by more than one host. For example, if you had several hosts where each name
started with either
eastern_region
orwestern_region
, you could select only those hosts in theeastern_region
by enteringeastern_region
in this field. - Groups: Enter either the full group name or part of the group name. For
example, if you have one host in
group1
and another ingroup2
, enteringgroup
displays both hosts. Enteringgroup1
enters only hosts ingroup1
. For more information about creating groups, see Managing Inventories and Groups. - Enabled: Set this to Yes to show all hosts available for jobs. Set it to No to display all hosts unavailable for jobs.
- Inventory ID: Enter the inventory ID for an inventory. You can find the
inventory ID for inventories using the
api/v2/inventories/
REST API endpoint. - Instance ID: Enter the instance ID for a control or execution node instance.
You can find the instance ID for inventories using the
api/v2/instances/
REST API endpoint. - Last job: Enter the job ID of a job that ran against one or more hosts. Each host that the job ran against appears. To obtain the job ID, see Viewing Jobs.
- Advanced: Perform more fine grained searches based on set types, various
keys, and lookup types such as
exact
,startswith
, and so on.
- Name: Enter either the full name of the host or a part of a name that might
be shared by more than one host. For example, if you had several hosts where each name
started with either
- To perform an advanced search based on stored facts generated from running playbooks on
existing hosts, do the following:
- Ensure a job has run to collect and store facts about the host to which this smart inventory applies. For more information about storing facts, see Setting Up a Job Template. For more information about viewing stored facts, see Managing Hosts.
- From the list, select Advanced.
- From the Key list, select ansible_facts.
- In the search field, enter the fact you want to search on. Valid parameters are:
()
for groupings,and
for adding two groupings together,__
to reference related fields in a relational field.__
to indicate separate ansible_facts.[]
to indicate a JSON array in the path.
-
The following lists all Oracle Linux based hosts.
ansible_distribution="OracleLinux"
- The following lists all hosts within the IPv4
100.102.112.0
network. Within the host facts, this value is specified by two parameters:ansible_default_ipv4
and the nested parameternetwork
. The use of the__
parameter in the search indicates that these are distinct but related parameters.ansible_default_ipv4__network="100.102.112.0"
- The following lists all hosts using the
AuthenticAMD
processor. Within the host facts, this value is part of an array and appears within brackets[]
after theansible_processor
parameter, and so brackets[]
are used in the search for this kind of value.ansible_processor[]="AuthenticAMD"
- After defining the search, click Select.
The search appears within the Smart host filter field. Click the search icon again to add or remove searches.
-
In the Variables field (a code box), you can enter YAML or JSON code to specify any inventory variables by doing the following:
- Click the YAML or the JSON button to specify which syntax to use.
- Type the variables in the code edit box.
-
Click Save.
- You can optionally configure Oracle Linux Automation Manager to update the memberships
of smart inventories more frequently, by adding the following setting to the
/etc/tower/conf.d/<configuration file>.py file (where <configuration
file> is the name of the configuration file) on the control or hybrid nodes.
AWX_REBUILD_SMART_MEMBERSHIP=True
This updates memberships in the following events:- When a new host is added
- When an existing host is modified (updated or deleted)
- When a new Smart Inventory is added
- When an existing Smart Inventory is modified (updated or deleted)
Note:
Enabling this parameter increases the load on the system.
Managing External Inventory Sources
- Manually by using the UI,
- Automatically according to a schedule,
- Automatically every time a job runs that uses the inventory.
Creating a Dynamic inventory
-
Log into Oracle Linux Automation Manager with an administrator user account.
- Create an inventory as described in Managing Inventories and Groups.
- Create a project configured with access to a GIT inventory as described in Managing Projects.
-
From the Resources section, click Inventories.
The Inventories page appears.
- Select the inventory you created.
- Click Sources.
- Click Add.
The Create new source page appears.
- In the Name field, enter a name.
- From the Execution Environment list, click the search button and select an execution
environment to use when running the job that imports the inventory from the remote
repository.
Note:
If you leave this field blank, the default execution environment is used. For more information about default execution environments, see Oracle Linux Automation Manager 2.3: Release Notes.
- From the Source list, select Sourced from a Project.
A new section appears called Source details.
- From the Credential list, click the search button and select a credential to use, if required. For example, you could select a inventory file that requires further authentication, such as an inventory for Oracle Cloud Infrastructure (OCI) would require an OCI credential. For more information, see Setting Up an Oracle Cloud Infrastructure Credentials.
- From the Project list, click the search button and select a project to use that includes a git repository which includes an inventory.
- In the Inventory File field, enter the path and name of the inventory file. For more
information about valid inventory formats, see Inventory File Formats.
Note:
The inventory path begins at the root directory of the git repository. If the inventory file is at the root level of the repository, enter the name of the repository file. If the inventory file is within one or more folders, enter the name of the first folder without a slash, then include slashes before each sub folder. For example,inventory/north_america/inventory.yaml
. - As you type the path and name of the inventory file, the Set source to path to field appears and duplicates the inventory path and file name. When you have finished typing in the inventory path and file name, click this field to select the inventory.
- From the Verbosity list, enter a verbosity level. This decides the level of output the
inventory job update produces. Valid values are:
- 0 (Warning)
- 1 (Info)
- 2 (Debug)
- From the Update options area, select the following if required:
- Overwrite: Enable this option to remove hosts and groups from the inventory that are no longer present in the external source. Unmanaged hosts and groups move to the next manual group or stay in the "all" group if none exist. If disabled, unmanaged hosts and groups remain unchanged during updates.
- Overwrite variables: Enable this option to replace all variables for child groups and hosts with those from the external source. Disable it to merge local variables with external ones instead.
- Update on launch: Enable this option so that whenever a job runs using this inventory, the inventory is refreshed first.
- Click Save.
- Click Sync to synchronize the source information. This triggers a synchronization job that you can view from the Jobs area. See Viewing Jobs for more information.
- After the synchronization, return to the main inventory page and review the Hosts and Groups tab for imported host and group information.
Inventory File Formats
When running inventories from a project, Inventory sources can point to a file in various formats or a script plugin. The following sections provide information about the various file formats you can use.
yaml Inventory
Valid extensions available for a YAML inventory file include .yaml
,
.yml
, and .json
. The YAML inventory structure includes the
following elements:
all
: The file must begin with theall
group.hosts
: Under theall
group,hosts
specifies individual host definitions that can have nested entries treated as variables.vars
: You can optionally use this element with any defined group to include one or more variables.children
: You can optionally use this to specify child groups that can recursively contain their own hosts, vars, and children.
The following is an example YAML inventory file:
---
all:
children:
web:
vars:
environment: web
timezone: UTC
children:
prod:
vars:
env_type: production
debug_mode: False
hosts:
web1:
ansible_host: 192.0.2.254
http_port: 80
server_name: web1.example.com
web2:
ansible_host: 192.0.2.253
http_port: 8080
server_name: web2.example.com
dev:
vars:
env_type: development
debug_mode: True
hosts:
dev-web1:
ansible_host: 192.0.2.252
http_port: 8081
server_name: dev-web1.example.com
dev-web2:
ansible_host: 192.0.2.251
http_port: 8082
server_name: dev-web2.example.com
db:
vars:
database_version: 5.7
backup_schedule: daily
hosts:
db1:
ansible_host: 192.0.2.250
db_username: admin
db_password: password
INI Inventory
The valid extension for an INI inventory file is .ini
. The INI inventory
structure includes the following elements:
- Sections start with a header in square brackets
[]
, for example,[webservers]
. - Each section represents a group or category of hosts.
- Section headers can't be empty.
- Modifiers can be added to section headers, such as:
:children
to indicate that the group contains subgroups.:vars
to indicate that the group contains variables assigned to all members.
- Hosts are defined by listing their names under a section header, one per line.
- Hosts can have variables defined inline as key-value pairs separated by
=
. - Ungrouped hosts must appear under the
[ungrouped]
section.
- Values passed in the INI format using the
key=value
syntax are interpreted differently depending on where they're declared within an inventory. - When declared under a host, values are treated as host-specific variables.
- When declared under a group with the
:vars
modifier, values are treated as group-wide variables. - When declared under the
[ungrouped]
section, values are treated as global variables.
The following is an example INI inventory file:
[all]
; List of all hosts
host1 ansible_host=192.0.2.10
host2 ansible_host=192.0.2.20
host3 ansible_host=192.0.2.30
[web]
host1
host2
[web:vars]
http_port=80
server_name=example.com
[web:children]
dev
staging
[dev]
dev-host1 ansible_host=192.0.2.50
dev-host2 ansible_host=192.0.2.51
[dev:vars]
debug_mode=True
log_level=DEBUG
[staging]
stg-host1 ansible_host=192.0.2.100
stg-host2 ansible_host=192.0.2.101
[staging:vars]
debug_mode=False
log_level=INFO
[db]
host3
[db:vars]
db_username=admin
db_password=password
database_version=5.7
[ungrouped]
ungrp-host1 ansible_host=192.0.2.200
ungrp-host2 ansible_host=192.0.2.201
TOML Inventory
The valid extension for a TOML inventory file is .TOML
. The TOML Inventory
structure follow the specification found at https://toml.io/en/v1.0.0:
[all.vars]
environment = "all"
[web.vars]
environment = "web"
timezone = "UTC"
[web.hosts.web1]
ansible_host = "192.0.2.254"
http_port = 80
server_name = "web1.example.com"
env_type = "production"
debug_mode = false
[web.hosts.web2]
ansible_host = "192.0.2.253"
http_port = 8080
server_name = "web2.example.com"
env_type = "production"
debug_mode = false
[web.hosts.dev-web1]
ansible_host = "192.0.2.252"
http_port = 8081
server_name = "dev-web1.example.com"
env_type = "development"
debug_mode = true
[web.hosts.dev-web2]
ansible_host = "192.0.2.251"
http_port = 8082
server_name = "dev-web2.example.com"
env_type = "development"
debug_mode = true
[db.vars]
database_version = "5.7"
backup_schedule = "daily"
[db.hosts.db1]
ansible_host = "192.0.2.250"
db_username = "admin"
db_password = "password"
Script Plugin
The valid extension for an python script file .py
. The following is an
example an inventory script that generates inventory data based on an inventory file find in
the same directory as the script:
#!/usr/bin/env python3
"""
Generates an Ansible inventory from a JSON payload file.
"""
import json
def load_json_payload(file_path: str) -> dict:
"""
Loads JSON payload from a file.
Args:
- file_path (str): Path to the JSON payload file.
Returns:
- dict: Parsed JSON payload.
"""
try:
with open(file_path, 'r') as json_file:
return json.load(json_file)
except FileNotFoundError:
print(f"File '{file_path}' not found.")
return {}
except json.JSONDecodeError as e:
print(f"Failed to parse JSON: {e}")
return {}
def create_group(inventory: dict, group_name: str, hosts: list) -> None:
"""
Creates a new group in the inventory.
Args:
- inventory (dict): Ansible inventory dictionary.
- group_name (str): Name of the group to create.
- hosts (list): List of hosts to add to the group.
"""
if group_name not in inventory:
inventory[group_name] = {'hosts': []}
inventory[group_name]['hosts'].extend(hosts)
def generate_ansible_inventory(payload: dict) -> dict:
"""
Generates an Ansible inventory from the given JSON payload.
Args:
- payload (dict): Parsed JSON payload.
Returns:
- dict: Generated Ansible inventory.
"""
inventory = {
'_meta': {'hostvars': {}},
'all': {'hosts': [], 'vars': {}}
}
os_groups = {}
location_groups = {}
for host in payload.get('hosts', []):
host_id = host.get('id')
hostname = host.get('hostname')
ip_address = host.get('ip_address')
status = host.get('status')
os = host.get('os')
location = host.get('location')
owner = host.get('owner')
if not all([host_id, hostname, ip_address, status, os, location, owner]):
continue # Skip hosts with missing information
inventory['all']['hosts'].append(ip_address)
host_vars = {
'ansible_host': ip_address,
'status': status,
'os': os,
'location': location,
'owner': owner
}
inventory['_meta']['hostvars'][ip_address] = host_vars
create_group(os_groups, os, [ip_address])
create_group(location_groups, location, [ip_address])
inventory.update(os_groups)
inventory.update(location_groups)
return inventory
if __name__ == '__main__':
json_payload_file = 'labs/json-payload'
payload = load_json_payload(json_payload_file)
inventory = generate_ansible_inventory(payload)
print(json.dumps(inventory))
json_payload
:
{
"hosts": [
{
"id": 1,
"hostname": "host1.example.com",
"ip_address": "192.168.1.101",
"status": "active",
"os": "Oracle_Linux_8",
"location": "Ottawa",
"owner": "User_4"
},
{
"id": 2,
"hostname": "host2.example.com",
"ip_address": "192.168.1.102",
"status": "inactive",
"os": "Oracle_Linux_8",
"location": "Texas",
"owner": "User_1"
},
{
"id": "3",
"hostname": "host3.example.com",
"ip_address": "192.168.1.10",
"status": "active",
"os": "Oracle_Linux_9",
"location": "West_Coast",
"owner": "admin_1"
},
{
"id": "4",
"hostname": "host4.example.com",
"ip_address": "192.168.1.11",
"status": "active",
"os": "Oracle_Linux_9",
"location": "West_Coast",
"owner": "admin_2"
},
{
"id": "5",
"hostname": "host5.example.com",
"ip_address": "192.168.1.15",
"status": "inactive",
"os": "Oracle_Linux_7",
"location": "East_Coast",
"owner": "user_1"
},
{
"id": "6",
"hostname": "host6.example.com",
"ip_address": "192.168.1.16",
"status": "inactive",
"os": "Oracle_Linux_7",
"location": "East_Coast",
"owner": "user_2"
},
{
"id": "7",
"hostname": "host7.example.com",
"ip_address": "192.168.1.16",
"status": "inactive",
"os": "Oracle_Linux_7",
"location": "Ottawa",
"owner": "user 3"
}
]
}
OCI Inventory
Valid extensions for OCI inventory files are .oci.yml
or
.oci.yaml
. The following is an example an OCI inventory file that generates
inventory data based on an OCI tenancy and compartment. The tenancy information is provided by
the associated OCI credential. The compartment OCID is specified in the inventory file:
---
plugin: oracle.oci.oci
regions:
- us-ashburn-1
compartments:
- compartment_ocid: "<sample-ocid>"
fetch_compute_hosts: true
hostname_format_preferences:
- "public_ip"
- "private_ip"
Note:
To run an OCI inventory, you must use a version of an Oracle Linux Automation Engine Execution Environment that includes the OCI SDK and the OCI Ansible Collection. For more information, see Oracle Linux Automation Manager 2.3: Release Notes. For more information about configuring an OCI Ansible Inventory, see https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/ansibleinventoryintro.htm.Setting Up Credentials
Oracle Linux Automation Manager provides functionality to create and store various types of credentials needed for working with private repositories and target inventory hosts. Examples of such credentials include:
-
Git Credentials:
Git credentials are used to access private registries you might be using as a source of projects and playbooks, and container images for any execution environments. They can include usernames and passwords, and SCM Private keys and passphrases.
-
Machine credentials:
Machine credentials are used to access target hosts through ssh. For example, a machine credential could be a username and password pair, or a username and ssh private key.
-
Orace Cloud Infrastructure:
Oracle Cloud Infrastructure (OCI) credentials are used to access OCI machines or inventory. You must use OCI credentials using jobs running on the version of Oracle Linux Automation Engine Execution Environment that includes the OCI SDK. For more information about Oracle Linux Automation Engines Execution Environments that include the OCI SDK, see Oracle Linux Automation Manager 2.3: Release Notes.
In Oracle Linux Automation Manager the credentials you enter are encrypted before being stored to the database. The encryption/decryption algorithm uses a variation of Fernet: a symmetric encryption cipher using AES-256 in CBC mode alongside a SHA-256 HMAC. The key is derived from the SECRET_KEY, which is set in the Oracle Linux Automation Manager installation (see Oracle Linux Automation Manager 2.3: Installation Guide for more details).
The credentials are decrypted when they're extracted and used.
The following sections provide information about setting up various kinds of credentials on Oracle Linux Automation Manager.
Setting Up Git Credentials
To set up Git credentials, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Credentials.
The Credentials page appears.
-
Click the Add button.
The Create New Credential page appears.
-
In the Name field, enter the name of the credential. For example,
GitCredential1
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the organization list, select an organization.
-
Click Select.
-
From the Credential Type list, select Source Control.
-
In the UserName field, enter the username, if required.
-
In the Password field, enter a password, if required.
-
In the SCM Private Key field, enter the SSH private key (if you're using SSH authentication) that you set up on the host running Oracle Linux Automation Manager.
-
In the Private Key Passphrase field, enter a passphrase (if you have set up a passphrase for SSH authentication).
-
Click Save.
Setting Up an Oracle Cloud Infrastructure Credentials
To set up Oracle Cloud Infrastructure (OCI) credentials, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Credentials.
The Credentials page appears.
-
Click the Add button.
The Create New Credential page appears.
-
In the Name field, enter the name of the credential. For example,
OCICredential
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the organization list, select an organization.
-
Click Select.
-
From the Credential Type list, select Oracle Cloud Infrastructure.
-
In the User OCID field, enter the OCID.
-
In the Fingerprint field, enter a fingerprint.
-
In the Tenant OCID field, enter the tenant OCID.
- In the Region field, enter the region.
-
In the Private Key field, enter the SSH private key.
-
In the Private User Key Passphrase field, enter a passphrase (if you have set up a passphrase for SSH authentication).
-
Click Save.
Setting Up Machine Credentials
Machine credentials are used to access target hosts through ssh.
To set up a machine credential, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Credentials.
The Credentials page appears.
-
Click the Add button.
The Create New Credential page appears.
-
In the Name field, enter the name of the credential. For example,
InventoryMachineCredential1
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the organization list, select an organization.
-
Click Select.
-
From the Credential Type list, select Machine.
-
In the Username field, enter the username, if required.
-
In the Password field, enter a password, if required.
-
Select Prompt on launch checkbox above the Password field if you want a password prompt to appear when launching job templates or job workflows against an inventory.
-
In the SSH Private Key field, enter the SSH private key that Oracle Linux Automation Engine uses to access target hosts when using SSH authentication if required.
-
In the Signed SSH Certificate field, enter a signed SSH certificate, if required.
-
In the Private Key Passphrase field, enter a passphrase (if you have set up a passphrase for SSH authentication).
-
Select the Prompt on launch checkbox above the Private Key Passphrase field if you want a private key passphrase prompt to appear when launching job templates or job workflows against an inventory.
-
From the Privilege Escalation Method list, select an escalation method if the playbooks you run in the machine require an escalation method, for example,
sudo
. -
In the Privilege Escalation Username field, enter the username, if required.
-
In the Privilege Escalation Password field, enter a password, if required.
-
Select Prompt on launch above the Privilege Escalation Password field if you want a password prompt to appear when launching job templates or job workflows against an inventory.
-
Click Save.
Setting Up Ansible Galaxy/Automation Hub API Token Credentials
Oracle Linux Automation Manager provides the Ansible Galaxy/Automation Hub Api Token credential type to enable you to access and download collections from a repository location. For example, you might create the following credentials:
-
A credential called
My Ansible Galaxy Credential
, to accesses the publicly open location https://galaxy.ansible.com/. Such a location, being publicly open, doesn't require you to enter any authentication information, such API Token, into the credential. -
A credential called
My Private Auto Hub API Token Credential
, to access one of the Private Automation Hub repositories, for example athttps://myprivateautomationhub/published
. Such a location would require authentication, so you would enter an API Token obtained from the Private Automation Hub console associated with that registry.
You can add more than one Ansible Galaxy/Automation Hub API Token credential to an organization. The order in which you add the credentials to an organization is important as it determines the order in which repositories are searched when collections are to be downloaded for a project assigned to that organization.
Important:
Ensure You Have Enabled the Download of Collections and Roles
To allow collections and roles listed in an SCM project requirements.yml
to be dynamically downloaded, you must enable the following Job Settings:
-
Enable Collection(s) Download
-
Enable Role Download
Note:
These settings are enabled by default when you first install Oracle Linux Automation Manager.
To edit Job settings:
-
Click Settings in the left-hand navigation menu.
-
Click the Job settings link.
-
Click Edit and proceed to edit the settings.
- Click Save.
The following examples show you the steps to follow to create such credentials.
Setting Up an Ansible Galaxy Credential
Note:
TheAnsible Galaxy
credential is created by default
when you install Oracle Linux Automation Manager.
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Credentials.
The Credentials page appears.
-
Click the Add button.
The Create New Credential page appears.
-
In the Name field, enter the name of the credential. For example,
My Ansible Galaxy Credential
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the organization list, select an organization.
-
Click Select.
-
From the Credential Type list, select Ansible Galaxy/Automation Hub API Token.
-
In the Galaxy Server URL field, enter the galaxy ansible URL https://galaxy.ansible.com/.
-
Click Save.
Setting Up a Private Automation Hub Collections Credential
Private Automation Hub credentials are used to access a Private Automation Hub instance using a URL and API token which contains collections in various repositories.
To set up a Private Automation Hub credential for accessing collections, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Credentials.
The Credentials page appears.
-
Click the Add button.
The Create New Credential page appears.
-
In the Name field, enter the name of the credential. For example,
My Private Auto Hub API Token Credential
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the organization list, select an organization.
-
Click Select.
-
From the Credential Type list, select Ansible Galaxy/Automation Hub API Token.
-
In the Galaxy Server URL field, enter a Private Automation Hub repository URL. For more information about different repository types, see Oracle Linux Automation Manager 2.3: Private Automation Hub User's Guide.
- In the API Token field, enter an Private Automation Hub API token. For more information about creating an API token in Private Automation Hub, see Oracle Linux Automation Manager 2.3: Private Automation Hub User's Guide.
-
Click Save.
Setting Up Container Registry Credentials for an Execution Environment
To set up a Private Automation Hub credentials for accessing collections, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Credentials.
The Credentials page appears.
-
Click the Add button.
The Create New Credential page appears.
-
In the Name field, enter the name of the credential. For example,
Registry Credentials
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the organization list, select an organization.
-
Click Select.
-
From the Credential Type list, select Container Registry .
-
In the Authentication URL field, enter the IP address or host name of the container registry you want to connect with. For example, this might be a Private Automation Hub instance hosting your execution environment container images or it could be https://container-registry.oracle.com/. For more information about Private Automation Hub, see Oracle Linux Automation Manager 2.3: Private Automation Hub User's Guide.
- In the Username field, enter the username of the container registry user that has access to the execution environment images you need.
- In the Password or Token field, enter the password for the user.
- Enable Verify SSL if the container registry is configured for SSL authentication.
-
Click Save.
Setting Up Credentials Permissions
Note:
You can only assign credential access to users and teams that belong to the same organization that the credential belongs to.To assign users and teams permissions to use a credential perform the following steps:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Credentials.
The Credentials page appears.
-
Select an existing credential.
The selected credential is displayed with the Details tab active.
-
Click the Access tab.
The Access tab lists users that already have access to the credential, for example users with full administrative privileges.
-
Click the Add button.
The Add Roles page appears and shows options Users and Teams.
-
Click one of the options. For example, Users.
A list of available users appears.Note:
Users with full administrator privileges don't appear because they have permissions for all entities in Oracle Linux Automation Manager.
-
From the left column, select the checkbox beside each user you want to provide permission to use the credential.
-
Click Next.
The permissions you can assign to selected users is displayed.
- Select the checkbox beside each permission you want to assign to the selected users.
-
Click Save.
The previous example assumes that users, rather than teams, are being assigned new roles to access the credential. If instead of users you want to assign access to teams, then you follow the same steps as the previous procedure except you choose teams rather than users when asked to specify which resource type you're configuring with new permissions.
Setting Up Job Templates
The following sections provide information about setting up job templates.
Setting Up a Job Template
Job Templates let you run playbooks tasks that are associated with a project against the hosts contained in an inventory. From a job template, you can also specify:
-
Permissions: Which teams, users, or both can run the job.
-
Notification: What notifications the job template triggers.
-
Completed Jobs: A list of all completed jobs.
-
Schedules: A list of schedules for when a job runs.
To set up a job template, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Templates.
The Templates page appears.
-
Click the Add button.
A menu appears.
-
Click the Add job template option.
The Create New Job Template page appears.
-
In the Name field, enter a name for the job template. For example,
JobTemplate1
. -
From the Job Type list, select one of the following:
-
Run: Runs the playbook.
-
Check: Checks that the playbook can run without errors.
-
-
Select the Prompt on launch checkbox next to the Job Type field if you want a dialog box to confirm the choice of job type when the job is launched.
Note:
Some fields have a Prompt on launch checkbox displayed next to them. Selecting such a checkbox next to a field means a dialog is displayed when the job is launched to confirm the value to be used for the field.
-
In the Inventory field, click the search button.
The Select Inventory dialog appears.
-
From the inventory list, select the inventory containing the hosts you want this job to manage.
-
In the Project field, click the search button.
The Select Project dialog appears.
-
Select the project containing the playbook you want this job to run.
For example, you might select a project that contains the following sample Oracle Linux Automation Engine playbooks:- The sample Yum playbook that runs a yum update on the inventory.
- The sample httpd playbook that creates an httpd server on the inventory's host.
For more information, see Setting Up and Running Sample Playbooks.
- In the Execution Environment field, click the search button.
The Select Execution Environment dialog appears.
- Select the execution environment you want this job to use.
If you don't select an environment, the command runs on the default execution environment depending on the version of Oracle Linux Automation Manager you are running. For more information about execution environments, see Oracle Linux Automation Manager 2.3: Release Notes.
-
From the Playbook list, select a playbook from the selected project. For example, if you're using the sample Yum playbook, select
yum_update.yaml
. -
In the Credentials field, click the search button.
The Select Credentials dialog appears.
- From the Selected Category list, select the one of host categories to display available credentials.
-
Select a credential you have set up to access the hosts specified in the inventory you selected, if required.
-
In the Labels field, enter a label that describes the job. You can use these labels in various Oracle Linux Automation Manager views to group and filter job templates and completed jobs.
-
In the Variables field (a code box), you can enter YAML or JSON code to pass extra command-line variables to the playbook by doing the following:
- Click the YAML or the JSON button to specify which syntax you want to use.
- Type the variables in the code edit box.
-
In the Forks field, use scroll arrows to select the number of forks allowed. This is the number of parallel or simultaneous processes that can run while executing an Oracle Linux Automation Engine playbook. An empty value or a value of 1 uses the default specified in
/etc/ansible/ansible.cfg
. -
In the Limit field, you can enter one or more hostname, IP address, or group name, separated by comma, that further limit the hosts specified in the inventory where the job can run, if required. For example, to run a job on only hosts included in a group in the inventory that's called group1, enter
group1
. To run the job against two groups called group1 and group2, entergroup1,group2
. -
From the Verbosity list, select a level of output that Oracle Linux Automation Manager displays as the job template runs. Options are as follows:
-
0 (Normal)
-
1 (Verbose)
-
2 (More Verbose)
-
3 (Debug)
-
4 (Connection Debug)
- 5 (WinRM debug)
-
-
In the Job Slicing field, use scroll arrows to select the number of job slices allowed. Job slices enable you to divide the work done by a job template into the specified number of job slices, each running the same tasks against a part of the inventory.
-
In the Timeout field, use scroll arrows to select the time in seconds before a job times out.
-
Enable Show Changes to show the changes made by an Oracle Linux Automation Engine task in a job output.
-
In the Instance Groups field, click the search button.
The Select Instance Groups dialog appears.
- Select one or more instance groups you created when you installed Oracle Linux Automation Manager.
-
In the Job Tags field, enter one or more job tags. Tags enable you to run portions of large playbook that contain tags. You can specify more than one tag using commas to separate each tag.
-
In the Skip Tags field, enter one or more job tags to skip. You can specify more than one tag using commas to separate each tag.
-
In the Options section, check the following options if required:
-
Privilege Escalation: The playbook runs with administrator privileges.
-
Provisioning Callbacks: Creates a provisioning callback URL so a host can contact Oracle Linux Automation Manager and request a configuration update using this job template.
-
Enable Webhook: The playbook enables webhooks.
-
Concurrent Jobs: Oracle Linux Automation Manager can run several instances of the job template at the same time.
-
Enable Fact Storage: Uses facts gathered from playbooks run against hosts and stores discovered facts in the cache. To view gathered facts, see Managing Hosts.
Note:
Playbooks gather facts by default unless fact gathering is explicitly disabled in the playbook. If the playbook disables fact gathering, this option has no effect. - Prevent Instance Group Fallback
Enable to prevent adding any inventory or organization instance groups to the list of preferred instances groups to run the job template on. If the list is empty, the global instance groups is applied.
-
-
Click Save.
Setting Up and Running Sample Playbooks
When you install Oracle Linux Automation Manager, sample Oracle Linux Automation Engine
playbooks are also included in the
/var/lib/ol-automation-manager/projects/demo_bundled
directory. This
directory contains the following playbooks:
-
httpd.yaml
: This playbook installs an Apache HTTP server on the target inventory. -
yum_update.yaml
: This playbook runs a yum update on the target inventory.
To set up and run these playbooks as the admin user, do the following:
-
Log into Oracle Linux Automation Manager as the admin user.
-
Set up an organization, for example
Sample Yum and Apache Org
. For more information, see Setting Up Organizations. -
Set up credentials for the hosts where you want to run the playbooks as required, for example
Sample Yum and Apache Host Credential
. For more information, see Setting Up Machine Credentials. -
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Projects.
The Projects page appears.
-
Click the Add tab.
The Create New Project page appears.
-
In the Name field, enter a name, for example,
Sample Yum and Apache project
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the Organization List, select an organization you have created, for example
Sample Yum and Apache Org
. -
From the Source Control Credential Type list, select Manual.
-
From the Playbook Directory list, select demo_bundled.
-
Click Save.
Note:
For more information on creating projects see Managing Projects -
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Inventory.
The Inventories page appears.
-
Click the Add button.
A menu appears.
-
Click the Add Inventory option.
The Create new inventory page appears.
-
In the Name field, enter a name for the inventory. For example,
Sample Yum an Apache Inventory
. -
In the Organization field, click the search button.
The Select Organization dialog appears.
-
From the Organization list, select an organization you have created, for example,
Sample Yum and Apache Org
. -
Click Save.
Note:
For more information on creating inventories see Managing Inventories and Groups -
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Hosts.
The Hosts page appears.
-
Click the Add button.
The Create New Host page appears.
-
In the Name field, enter the IP address or host name of the system you're connecting to. The host must be reachable.
- In the Inventory field click the search button.
The Select Inventory page appears.
-
From the inventory list, select an inventory you have created, for example
Sample Yum and Apache Inventory
. - Click Save.
Note:
Also see Managing Hosts for information on setting up hosts for an inventory. -
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Templates.
The Templates page appears.
-
Click the Add button.
A menu appears.
-
Click the Add job template option.
The Create New Job Template appears.
-
In the Name field, enter a name for the job template. For example,
Sample Yum or Apache Job
. -
From the Job Type list, select Run.
-
From the Inventory list, select an inventory, for example
Sample Yum an Apache Inventory
. -
From the Project list, select a project, for example,
Sample Yum and Apache project
. -
From the Playbook list, select either
yum_update.yaml
to run a yum update on the host orhttpd.yaml
to set up an Apache instance on the host. -
From the Credentials lists, select a credential, for example
Sample Yum and Apache Host Credential
. -
From the Verbosity list, select 0 (Normal).
-
If you're running the
httpd.yaml
playbook, enable Enable Privilege Escalation so the playbook runs with administrator privileges. -
Click Save.
-
Click Launch.
- The Output page appears so you can observe the progress of the job.
Note:
For more information on setting up a template see Setting Up a Job Template
Setting Up Workflow Templates
The following sections provide information about setting up workflow templates.
About Workflow Templates
A workflow template lets you use a graphical tool, the Workflow Visualizer, to configure the run sequence of disparate components such as job templates and management jobs, as nodes in a linear graph-like design.
The components in a workflow don't have to share the same organizations and inventories.
Node Types in Workflow Templates
- Job Template
- Management Job
- Workflow Job Template
- Approval
- Project Syncs
- Inventory Source Sync
Workflow Design, Features, and Properties
The following list highlights some key aspects of workflow design, features, and properties:
-
Workflow Graphs Read From Left to Right
The Workflow Visualizer’s graph-like design is read from left to right. For example, if a workflow design has
example_node_1
on the left connected by a straight line toexample_node_2
to the right, this indicatesexample_node_1
runs immediately beforeexample_node_2
. -
Parent Nodes and Child Nodes
Continuing with the previous example, if
example_node_1
is configured to run immediately beforeexample_node_2
, thenexample_node_1
is said to be the parent node ofexample_node_2
.A node can have more than one parent node. For example, you might have a workflow where you configure parent nodes
RunSampleYumPlaybook
andRunSampleApachePlaybook
to run immediately before child nodeInstallWebApplication
. In such a case the Workflow Visualizer shows the lines from each parent node converging directly on child nodeInstallWebApplication
. -
Run Type Condition
When you add a child node you must select from one of the following options to stipulate the condition under which the child node should run:
-
On Success
(default):Select
On Success
to specify the child node you're adding should only run if the present node you're editing completes its run in a successful state. If you select this option, the connection to the added child node is shown as a green line. -
On Failure
:Select
On Failure
to specify the child node you're adding should only run if the present node you're editing completes its run in a failure state. If you select this option, the connection to the added child node is shown as a red line. -
Always
:Select
Always
to specify the child node you're adding should always run, regardless of the final state of the present node you're editing. If you select this option, the connection to the added child node is shown as a blue line.
-
-
Convergence Property
The Convergence property of a node determines whether it runs based on the final status of the parent nodes that converge directly to it. This option is significant if the node has more than one parent node linking directly to it. You can select one of the following values for the Convergence property:-
Any
(default): TheAny
option stipulates this node can run if any of the nodes that converge on this node complete as specified. -
All
: TheAll
option implies this node can only run if all the nodes that converge on this node complete as specified.
-
Setting Up a Workflow Template
Note:
For the purposes of the example, it's assumed the aim is to create a workflow of job templates that run the following sample playbooks:yum_update.yaml
: This playbook runs a yum update on the target inventory.httpd.yaml
: This playbook installs an Apache HTTP server on the target inventory.
-
Create a job template named
RunSampleYumPlaybook
that runs the playbookyum_update.yaml
against an inventory of servers. -
Create a job template named
RunSampleApachePlaybook
that runs the play bookhttpd.yaml
against an inventory of servers. -
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Templates.
The Templates page appears.
-
Click the Add button.
A menu appears.
-
Click the Add workflow template option.
The Create New Workflow Template page appears.
-
In the Name field, enter a name for the workflow template. For example,
SampleWorkflowTemplate
.Note:
The Name field is the only mandatory field on this page. The organization and inventory fields, for example, don't have to be set at the workflow level. -
Click Save.
The Workflow Visualizer page is displayed in the browser with a Start button.
-
Click the Start button in the Workflow Visualizer page.
-
The Add Node dialog appears.
-
The Node Type drop down list at the top of the Add Node dialog lets you select the type of resource to be added as a node. Accept the default choice of
Job Template
. -
Select
RunSampleYumPlaybook
from the list of available job templates. -
Accept the default option (
Any
) from the Convergence drop down list.Note:
The property is only significant of the node you're adding has more than one parent converging on it. -
Optionally enter a Node Alias to the node to be displayed with a particular display name, different to the resource name, in the Workflow Visualizer.
-
Click Save.
The Add Node dialog is dismissed.
The added node appears in the Workflow Visualizer.
-
-
Hover the mouse over the newly added node.
A small toolbar appears within the Workflow Visualizer next to the node.
-
Click the add ("+") icon on the toolbar to add another node after the first node.
-
The Add Node dialog appears.
- As this is the second node in the sequence the dialog initially displays the
following Run Type conditions to select from:
On Success
.On Failure
.Always
.
Accept the option selected by default (
On Success
). -
Click Next.
The Add Node dialog at this stage displays the same fields (Node Type, Convergence, Node Alias) as discussed earlier in the instructions dealing with the first node.
-
Select
RunSampleApachePlaybook
and complete the fields -
Click Save.
The Add Node dialog is dismissed.
The added node,RunSampleApachePlaybook
, appears in the Workflow Visualizer.Note:
The newly added node,RunSampleApachePlaybook,
appears to the right of the first node (its parent) and the 2 nodes are connected by a green line (the green line indicates that the second node runs only after the first one completes successfully).
- As this is the second node in the sequence the dialog initially displays the
following Run Type conditions to select from:
-
Click Save on the top-right of the Workflow Visualizer.
The Workflow Visualizer is dismissed and the newly created workflow template is displayed with the details tab active.
-
Click Launch when you're ready to run the workflow.
The Output page is displayed and the node currently in the running state is shown with a flashing green icon in its top left corner. The second node (
RunSampleApachePlaybook
) upon successful completion of the parent (RunSampleYumPlaybook
).Upon successful completion of the workflow each job displays the time it took for it to complete
Creating Schedules for Resources
Oracle Linux Automation Manager lets you create schedules for the following resources:
-
Job Templates
-
Workflow Templates
-
Inventory Sources
-
Projects
The following example shows you how to create a schedule for a resource, in this case a job template:
-
Log into Oracle Linux Automation Manager.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Resources section, click Templates.
The Templates page appears displaying a list of available templates.
-
Click the name of the job template you want to create a schedule for.
A tabbed view of the job template appears. Initially the Details tab is open.
-
Switch to the Schedules tab.
-
Click the Add button.
The Create New Schedule dialog appears. Type a descriptive name in the Name field.
Take note of the value in the Local time zone field when completing the start date calendar and start time drop down list controls.Note:
Best Practice: Set Schedules in UTC time.
The application saves schedules in UTC, a world standard that isn't adjusted for daylight saving time. Therefore, to avoid any confusion involving seasonal clock changes, it's best to set and track schedules in UTC.
-
Click Save.
The schedule is saved and displayed on the Schedule Details page.
It also appears in the Schedules view.
Managing Execution Environments
The following sections provide an overview on execution environments and how to create and view the execution environments for a system.
About Execution Environments
Execution environments are portable container images in which Oracle Linux Automation Engine automation tasks run. Execution environments replace the Python virtual environments used in prior versions of the Oracle Linux Automation Engine product.
You can also use custom execution environments created with the Builder utility. These custom execution environments include the base components listed above with additional components added. For more information about the Builder utility, see Oracle Linux Automation Manager 2.3: Private Automation Hub User's Guide.
Note:
While the Builder utility lets you create custom execution environment, in the case of an issue with the custom execution environment, Oracle might ask you to revert to the provided OLAM-EE default image to troubleshoot the problem.As portable self-contained container images, execution environments let automation tasks run consistently across several platforms.
-
OLAM EE
-
Control Plane Execution Environment
Viewing the Execution Environment Pages
To view an execution environment, do the following:
-
Log into Oracle Linux Automation Manager.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Administration section, click Execution Environments.
The Execution Environments page displays a summary table relating to the execution environments available in the system. The table columns include those described in the following list:
-
Name
The Name column contains the name of the execution environment.
-
Image
The Image column contains the full image location, including the container registry, image name, and version tag, of the image used for the execution environment. For example, container-registry.oracle.com/oracle_linux_automation_manager/olam-ee:latest . Alternatively, the image location might be a Private Automation Hub instance hosting the olam-ee image or a custom image. For more information see, Oracle Linux Automation Manager 2.3: Private Automation Hub User's Guide.
-
Organization
The Organization column contains information about which organizations in your system can access the execution environment.
-
-
Click the name of an execution environment for more details.
The execution environment is displayed in a tabbed view with the Details tab active. In addition to the Name, Image and Organization fields, the Details tab contains some other fields, including the following:
-
Created
The Created field contains the date and time the execution environment was created.
-
Last Modified
The Last Modified column contains the date and time the execution environment was last modified.
-
Pull
The Pull field contains a value that stipulates the conditions under which Oracle Linux Automation Manager should pull the container image from its repository location before running a resource job. The following values are possible:
-
Always
This option stipulates that a container image is always pulled before running the container.
-
Missing
This option stipulates that a container image is only pulled if the image is not present before running the container.
-
Never
This option stipulates that a container image never pulled before running the container.
Important:
Keep the container images updated to ensure the images have the latest CVE fixes.
-
-
-
Click the Back to execution environments button (the first button in the tab header row) to get back to the Execution Environments page.
Creating Execution Environments
To create an execution environment, do the following:
-
Log into Oracle Linux Automation Manager.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Administration section, click Execution Environments.
- Click Add.
The Create new execution environment page appears.
-
In the Name field, enter the name of the execution environment.
-
In the Image field, enter the image location, including the container registry, image name, and version tag, of the image used for the execution environment. For example, container-registry.oracle.com/oracle_linux_automation_manager/olam-ee:latest . Alternatively, you can point to a Private Automation Hub instance hosting the olam-ee image or a custom image. For more information see, Oracle Linux Automation Manager 2.3: Private Automation Hub User's Guide.
- From the Pull list, select one of the following values that stipulates the
conditions under which Oracle Linux Automation Manager should pull the container image
from its repository location before running a resource job:
-
Always
This option stipulates that a container image is always pulled before running the container.
-
Missing
This option stipulates that a container image is only pulled if the image isn't present before running the container.
-
Never
This option stipulates that a container image never pulled before running the container.
Important:
Keep the container images updated to ensure the images have the latest CVE fixes.
-
-
Organization
The Organization field contains information about which organizations in the system can access the execution environment.
-
Registry credential
The Registry credential field contains information about which credential the system must use to connect to a container registry. For more information, see Setting Up Container Registry Credentials for an Execution Environment.
-
Click Save.
Managing Instance Groups
This chapter looks at how you create and manage instance groups with Oracle Linux Automation Manager.
About Instance Groups and Service Mesh Node Types
The service mesh provided by Oracle Linux Automation Manager is an overlay network that provides a mesh of nodes of different types, such as controller nodes and execution nodes, to let you manage jobs across different inventories.
Oracle Linux Automation Manager provides instance groups to enable you to organize the
different hosts in its service mesh into separate groups, depending upon their node type and
purpose. For example, to create an instance group called
mesh_nodes_for_production
with nodes to run jobs on production machines,
and another group called mesh_nodes_for_development_machines
to run jobs on
development servers.
The following list outlines key points about instance groups and nodes:
-
One Job Queue per Instance Group
Each instance group has its own job queue, and any node in the instance can process a job from that queue.
-
Configuration of Extra Nodes
The nodes initially available for association with Instance Groups are those you configured for the mesh topology during the installation process. If you require extra nodes, for example for a new instance group you have created, then you need to follow the same process you used to create the initial nodes (see Oracle Linux Automation Manager 2.3: Installation Guide for more information on configuring nodes for a mesh topology).
-
Nodes Can Belong to More Than One Instance Group
For example, you can make some nodes available across the cluster, whilst reserving others for a specific instance group.
-
Associating Instance Groups With Resources
By default, jobs are run on nodes in the
Execution
instance group you created during the installation process (see Oracle Linux Automation Manager 2.3: Installation Guide).However, if required, you can specify instance groups by associating them with one of the following resources:
-
Job Template
-
Inventory
-
Organization
When a job runs, Oracle Linux Automation Manager first checks the job template associated with the job to see which instance group the job should be assigned to. If no instance group is associated with the job template, Oracle Linux Automation Manager next checks the inventory resource linked to the job. If no instance group is associated with the inventory resource, the Organization resource is checked.
-
-
Instance Groups Provided by Default
Oracle Linux Automation Manager comes with the following instance groups:
-
controlplane
:The
controlplane
instance group contains control nodes. Control nodes run persistent Oracle Linux Automation Manager services, such as the task dispatcher, project and inventory updates, and system jobs, but not regular jobs. Control nodes don't have execution capability. -
execution:
The
execution
instance group contains execution nodes. Execution nodes run jobs underansible-runner
withpodman
isolation. Execution nodes only run user-space jobs.
-
The following sections show you how to view and edit instance groups, how to associate jobs and resources with specific instance groups, and how to create groups.
Viewing the Instance Groups Summary
To view the Instance Groups page, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account.
-
Display the left navigation menu if it's not already visible by switching the Global navigation menu button in the top-left corner of the page.
-
From the Administration section, click Instance Groups.
The Instance Groups page appears.
The Instance Groups page displays a summary table relating to the instance groups in the system. The table columns include those described in the following list:
-
Name
The Name column contains the name of the Instance Group. Clicking the name takes you to a tabbed view of that instance's properties. The Details tab is the active tab initially.
-
Running Jobs
The Running Jobs column contains the number of jobs associated with the instance group that are running.
-
Total Jobs
The Total Jobs column contains the sum of the number of jobs associated with the instance group that have completed, and the number of jobs associated with the group that are still running.
-
Capacity
The Capacity column displays a Used capacity progress bar that indicates the percentage of capacity of the instance group that's being used.
-
Action
The Action column displays an Edit instance group icon that lets you edit the instance.
Editing an Instance Group
The following sections show you how to edit an instance group and change properties on the nodes associated with the group.
Editing Instance Group Policy Properties
You can set the following Policy properties on an instance group:
-
Policy instance minimum
This is the minimum number of instances to be automatically assigned to the group when new provisioned instances come online.
-
Policy instance percentage
Minimum percentage of all instances to be automatically assigned to this group when new provisioned instances come online.
To set the policy properties of an instance group, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.
-
In the summary table displayed on the Instance Groups page, go to the row with the group whose policy instance properties you want to edit.
-
Click the Edit instance group icon in the Action column.
The Edit details page appears.
-
Enter values in the properties Policy instance minimum and Policy instance percentage fields.
-
Click Save.
The tabbed view of the instance appears.
Associating and Disassociating Nodes with a Group Instance
The following steps show you how to associate and disassociate nodes with a group instance:
-
Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.
-
In the summary table displayed on the Instance Groups page, go to the row with the group whose node association you're looking to change.
-
Click the group instance name in the Name column.
A tabbed view of that instance's properties appears. Initially the Details tab is open,
-
Click the Instances tab.
The node instances associated with the group are displayed in a table.
-
To associate more node instances with the group, do the following:
-
Click the Associate button.
The Select Instances dialog appears displaying available node instances.
-
Select the check boxes next to the nodes you want to associate with the group instance.
-
Click Save.
The Instances page will be displayed and the nodes you selected appear in the list on the page.
-
-
To disassociate nodes from the current group instance, do the following:
- Select the checkbox next to each host you want to disassociate from the current group and click
the Disassociate button.
A dialog asks you to confirm the actions.
-
Confirm the actions if you're happy to proceed by clicking Disassociate button on the dialog.
The dialog is dismissed and the nodes you disassociated from the group no longer appear in the list.
- Select the checkbox next to each host you want to disassociate from the current group and click
the Disassociate button.
Changing Node Instance Properties
The following procedures show you how to change the properties on a specific node.
A node instance's capacity determines how many forks it can run simultaneously. Capacity thus impacts the number of systems a node can run jobs for in parallel. To change a node instance's capacity, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.
-
In the summary table displayed on the Instance Groups page, go to the row with the group associated with the node you want to edit.
-
Click the group instance name in the Name column.
A tabbed view of that instance's properties appears. Initially the Details tab is open,
-
Click the Instances tab.
The node instances associated with the group are displayed in a table.
-
Go to the row with the node instance you want to change.
-
To adjust the Capacity, drag the slider control in the Capacity Adjustment column to the value of the choice.
Note:
- The change is saved automatically. No Save button is available.
- Consider whether the new capacity setting is suitable for other instance groups the node might belong to.
The enable/disable setting lets you control whether a node instance is available for jobs to be assigned to it. For example, you might need to temporarily disable one of the node instances for maintenance. To change a node instance's enable/disable setting, do the following:
-
Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.
-
In the summary table displayed on the Instance Groups page, go to the row with the group associated with the node you want to edit.
-
Click the group instance name in the Name column.
A tabbed view of that instance's properties appears. Initially the Details tab is open,
-
Click the Instances tab.
The node instances associated with the group are displayed in a table.
-
Go to the row with the node instance you want to change.
-
To change a node instance's enable/disable setting, toggle the enable-disable toggle switch in the Action column.
Note:
- The change is saved automatically. No Save button is available.
- Consider whether the new setting is suitable for other instance groups the node might belong to.
Creating an Instance Group
The following steps show you how to create an instance group:
- Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.
-
Click the Add button.
A menu appears.
-
Click the Add instance group option.
The Create new instance group appears.
-
In the Name field, enter a name for the instance group. For example,
NodesForDataCentre1
. -
Optionally, enter integers into the Policy instance minimum and Policy instance percentage field.
Note:
The policy instance fields are defined as follows:-
Policy instance minimum:
This is the minimum number of instances to be automatically assigned to the group when new provisioned instances come online.
-
Policy instance percentage:
Minimum percentage of all instances to be automatically assigned to this group when new provisioned instances come online
-
-
Click Save.
The newly created instance group is displayed in a tabbed view with the Details tab active.
-
Click the Instances tab to switch to the Instances tab.
The node instances associated with the group are displayed in a table.
-
To associate more node instances with the group, click the Associate button.
The Select Instances dialog appears displaying available node instances.
-
Select the check boxes next to the nodes you want to associate with the group instance.
Click Save.
The Instances page is displayed and the nodes you selected appear in the list on the page.