1. User's Guide
  2. Setting Up Resources

3 Setting Up Resources

This chapter describes setting up 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.

Setting Up 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:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Projects.

    The Projects page appears.

  4. Click the Add button.

    The Create New Project page appears.

  5. In the Name field, enter a name. For example, Project1.

  6. In the Organization field, click the search button.

    The Select Organization dialog appears.

    If your project has ansible collection requirements, you must ensure you select an organization that enables you to 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.

  7. Click Select.

  8. From the Source Control Credential Type list, select one of the following:

    • Manual:

      The Manual option enables you to select a local playbook located on the machine hosting Oracle Linux Automation Manager. You select the playbook of your choice from a drop-down list labeled Playbook Directory.

      See Accessing a Local Playbook for more information.

    • Git:

      The Git option enables you to use a playbook from a remote repository such as from Git. Selecting the Git option displays source control fields for you to complete so that you can access the remote repository of your choice.

      Go to Accessing a Remote Playbook on Git for information about setting up source details and credentials.

  9. Click Save.

Accessing a Local Playbook

To make a local playbook accessible to your instance of Oracle Linux Automation Manager, ensure you have the required administrative privileges and carry out the following steps:

  1. Log onto the server hosting Oracle Linux Automation Manager.
  2. Create a directory to store your 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.

  3. Copy or create playbook files in the directory. For sample playbooks, see /var/lib/ol-automation-manager/projects/demo_bundled.

  4. 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:

  1. 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/tree/v2.12.2/examples.

    Caution:

    As this is a public repository, Oracle is not responsible for examples contained therein.

  2. If you are using a private repository that requires SSH authentication, you must set up your SSH private and public keys on the system running Oracle Linux Automation Manager and copy the public key to your Git user account.

  3. Return to the Oracle Linux Automation Manager UI and from the New Projects page, in the Source Control URL field, enter a URL to the SCM repository.

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

  5. If you need to retrieve a refspec from a branch, in the Source Control Refspec field, enter a refspec.

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

  7. Click Save.

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

  9. Click Jobs settings.

    The Details page appears.

  10. Click the Edit button.

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

  12. Click Save.

    Note:

    If your 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.

Setting Up Inventories and Hosts

The following sections provide information about setting up inventories and hosts.

Setting Up an Inventory

An inventory is a collection of hosts against which jobs and commands can be launched.

To set up an inventory, do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Inventories.

    The Inventories page appears.

  4. Click the Add button.

    A menu appears.

  5. Click the Add Inventory option.

    The Create new inventory page appears.

  6. In the Name field, enter a name for your inventory. For example, Inventory1.

  7. In the Organization field, click the search button.

    The Select Organization dialog appears.

  8. From the Organization list, select an organization.

  9. Click Select.

  10. In the Variables field (a code box), you can enter YAML or JSON code if you want to specify any inventory variables by doing the following:
    1. Click the YAML or the JSON button to specify which syntax you wish to use.
    2. Type the variables in the code edit box.

  11. Click Save.

Setting Up a Host

The following sections show you different ways of navigating to a Create new host page.

Each host must belong to an inventory. To create a host by first selecting the inventory in which you wish to create the host, do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Inventories.

    The Inventories page appears with a list of available inventories.

  4. Click on the name of the inventory you in which you wish to set up a host.

    The inventory is displayed in the Details Tab.

  5. Click the Hosts tab to switch to the Hosts tab.

  6. Click the Add button.

    The Create new host page appears.

  7. In the Name field, enter the IP address or host name.

  8. Click Save.

The following steps show you an alternative method to the previous procedure for creating a host for a specific inventory:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Hosts.

    The Hosts page appears.

  4. Click the Add button.

    The Create New Host page appears.

  5. In the Name field, enter the IP address or host name.

  6. In the Inventory field click the search button.

    The Select Inventory page appears.

  7. From the inventory list, select an inventory.

  8. Click Select.

  9. Click Save.

Running One-Off Commands Against a Host

To run single commands using Oracle Linux Automation Engine built-in modules against one or more hosts in an inventory (similar to running a module on the command line), do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Inventories.

    The Inventories page appears with a list of available inventories.

  4. Click on the name of the inventory containing the hosts against which you wish to run a command.

    The inventory is displayed in the Details Tab.

  5. Click the Hosts tab to switch to the Hosts tab.

    The Hosts page appears listing any hosts associated with the inventory.

  6. Select the check box beside one or more hosts on the left side.

    Note:

    If you do not select any of the check boxes the system assumes you wish to run the command against all the hosts.

  7. Click the Run Command button.

    The Run Command page appears.

  8. From the Modules list, select a module. For example, ping.

  9. In the Arguments field, enter any arguments that are required by the selected module.

  10. Click Next.

    A list of available execution environments is displayed.

  11. Select the Execution Environment.

    If you do not select an environment, the command will run in the OLAM EE execution environment by default.

  12. Click Next.

    A list of available machine credentials is listed.

  13. Select the Machine Credential for the machines. See Setting Up Credentials for information about setting up credentials.

  14. Click Launch.

    The Output page appears showing the job operations in real-time and eventually displays a status of Success of Failed.

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:

  1. 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 your execution environments. They can include usernames and passwords, and SCM Private keys and passphrases.

  2. Machine credentials:

    Machine credentials are used to access target hosts through ssh. For example, a machine credential could be a user name and password pair, or a user name and ssh private key.

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 utilizing 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.1: Installation Guide for more details).

The credentials are decrypted when they are 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:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Credentials.

    The Credentials page appears.

  4. Click the Add button.

    The Create New Credential page appears.

  5. In the Name field, enter the name of the credential. For example, GitCredential1.

  6. In the Organization field, click the search button.

    The Select Organization dialog appears.

  7. From the organization list, select an organization.

  8. Click Select.

  9. From the Credential Type list, select Source Control.

  10. In the UserName field, enter the user name, if required.

  11. In the Password field, enter a password, if required.

  12. In the SCM Private Key field, enter the SSH private key (if you are using SSH authentication) that you set up on the host running Oracle Linux Automation Manager.

  13. In the Private Key Passphrase field, enter a passphrase (if you have set up a passphrase for SSH authentication).

  14. 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:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Credentials.

    The Credentials page appears.

  4. Click the Add button.

    The Create New Credential page appears.

  5. In the Name field, enter the name of the credential. For example, InventoryMachineCredential1.

  6. In the Organization field, click the search button.

    The Select Organization dialog appears.

  7. From the organization list, select an organization.

  8. Click Select.

  9. From the Credential Type list, select Machine.

  10. In the Username field, enter the user name, if required.

  11. In the Password field, enter a password, if required.

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

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

  14. In the Signed SSH Certificate field, enter a signed SSH certificate, if required.

  15. In the Private Key Passphrase field, enter a passphrase (if you have set up a passphrase for SSH authentication).

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

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

  18. In the Privilege Escalation Username field, enter the user name, if required.

  19. In the Privilege Escalation Password field, enter a password, if required.

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

  21. 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, does not 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 your Private Automation Hub repositories, located for instance at https://myprivateautomationhub/published. Such a location would require authentication, so you would have to 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:

Make Sure 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

To edit Job settings:

  1. Click Settings in the left-hand navigation menu.

  2. Click the Job settings link.

  3. Click Edit and proceed to edit the settings.

  4. Click Save.

The following examples show you the steps to follow to create such credentials.

Setting Up an Ansible Galaxy Credential

To set up an Ansible Galaxy Credential for accessing collections, do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Credentials.

    The Credentials page appears.

  4. Click the Add button.

    The Create New Credential page appears.

  5. In the Name field, enter the name of the credential. For example, My Ansible Galaxy Credential.

  6. In the Organization field, click the search button.

    The Select Organization dialog appears.

  7. From the organization list, select an organization.

  8. Click Select.

  9. From the Credential Type list, select Ansible Galaxy/Automation Hub API Token.

  10. In the Galaxy Server URL field, enter the galaxy ansible URL https://galaxy.ansible.com/.

  11. 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:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Credentials.

    The Credentials page appears.

  4. Click the Add button.

    The Create New Credential page appears.

  5. In the Name field, enter the name of the credential. For example, My Private Auto Hub API Token Credential.

  6. In the Organization field, click the search button.

    The Select Organization dialog appears.

  7. From the organization list, select an organization.

  8. Click Select.

  9. From the Credential Type list, select Ansible Galaxy/Automation Hub API Token.

  10. 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.1: Private Automation Hub User's Guide.

  11. 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.1: Private Automation Hub User's Guide.

  12. Click Save.

Setting Up Container Registry Credentials for your Execution Environment

Oracle Linux Automation Manager

To set up a Private Automation Hub credential for accessing collections, do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Credentials.

    The Credentials page appears.

  4. Click the Add button.

    The Create New Credential page appears.

  5. In the Name field, enter the name of the credential. For example, Registry Credentials.

  6. In the Organization field, click the search button.

    The Select Organization dialog appears.

  7. From the organization list, select an organization.

  8. Click Select.

  9. From the Credential Type list, select Container Registry .

  10. 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.1: Private Automation Hub User's Guide.

  11. In the Username field, enter the username of the container registry user that has access to the execution environment images you need.
  12. In the Password or Token field, enter the password for the user.
  13. Enable Verify SSL if your container registry is setup for SSL authentication.

  14. 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 carry out the following steps:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Credentials.

    The Credentials page appears.

  4. Select an existing credential.

    The selected credential is displayed with the Details tab active.

  5. Click the Access tab.

    The Access tab lists users that already have access to the credential, for example users with full administrative privileges.

  6. Click the Add button.

    The Add Roles page appears and shows options Users and Teams.

  7. Click one of the options. For example, Users.

    A list of available users appears.

    Note:

    Users with full administrator privileges do not appear because they have permissions for all entities in Oracle Linux Automation Manager.

  8. From the left column, select the check box beside each user you want to provide permission to use the credential.

  9. Click Next.

    The permissions you can assign to your selected users is displayed.

  10. Select the check box beside each permission you wish to assign to your selected users.

  11. Click Save.

In the previous example it is assumed that users, rather than teams, are being assigned new roles to access the credential. If instead of users you wish 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 are 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 allow you to run playbooks task that are associated to 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:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Templates.

    The Templates page appears.

  4. Click the Add button.

    A menu appears.

  5. Click the Add job template option.

    The Create New Job Template page appears.

  6. In the Name field, enter a name for your job template. For example, JobTemplate1.

  7. From the Job Type list, select one of the following:

    • Run: Runs the playbook.

    • Check: Checks that the playbook can run without errors.

  8. Select the Prompt on launch check box 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 check box displayed next to them. Selecting such a check box next to a field means a dialog is displayed when the job is launched to confirm the value to be used for the field.

  9. In the Inventory field, click the search button.

    The Select Inventory dialog appears.

  10. From the inventory list, select the inventory containing the hosts you want this job to manage.

  11. In the Project field, click the search button.

    The Select Project dialog appears.

  12. Select the project containing the playbook you want this job to execute.

    For example, you might select a project that contains the following sample Oracle Linux Automation Engine playbooks:
    • The sample Yum playbook that that runs a yum update on your inventory.
    • The sample HTTPD runbook that create an HTTPD on your inventory.

  13. Select the Execution Environment.

    If you do not select an environment, the command will run in the OLAM EE execution environment by default.

  14. From the Playbook list, select a playbook form your selected project. For example, if you are using the sample Yum playbook, select yum_update.yaml.

  15. From the Credentials lists, select a credential you have set up to access the hosts specified in the inventory you selected, if required.

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

  17. In the Variables field (a code box), you can enter YAML or JSON code if you want to pass extra command-line variables to the playbook by doing the following:
    1. Click the YAML or the JSON button to specify which syntax you wish to use.
    2. Type the variables in the code edit box.

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

  19. In the Limit field, you can enter the hostname patterns or IP addresses that further limit the hosts specified in the inventory where the job can run, if required.

  20. 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)

  21. 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 portion of the inventory.

  22. In the Timeout field, use scroll arrows to select the time in seconds before a job times out.

  23. Enable Show Changes to show the changes made by an Oracle Linux Automation Engine task in a job output.

  24. From the Instance Groups list, select the instance group you created when you installed Oracle Linux Automation Manager.

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

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

  27. 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 multiple instances of the job template at the same time.

    • Enable Fact Storage: Uses cached facts if available and stores discovered facts in the cache.

  28. 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 your target inventory.

  • yum_update.yaml: This playbook runs a yum update on your target inventory.

To set up and run these playbooks as the admin user, do the following:

  1. Log into Oracle Linux Automation Manager as the admin user.

  2. Set up an organization, for example Sample Yum and Apache Org. For more information, see Setting Up Organizations.

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

  4. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  5. From the Resources section, click Projects.

    The Projects page appears.

  6. Click the Add tab.

    The Create New Project page appears.

  7. In the Name field, enter a name, for example, Sample Yum and Apache project.

  8. In the Organization field, click the search button.

    The Select Organization dialog appears.

  9. From the Organization List, select an organization you have created, for example Sample Yum and Apache Org.

  10. From the Source Control Credential Type list, select Manual.

  11. From the Playbook Directory list, select demo_bundled.

  12. Click Save.

    Note:

    For more information on creating projects see Setting Up Projects

  13. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  14. From the Resources section, click Inventory.

    The Inventories page appears.

  15. Click the Add button.

    A menu appears.

  16. Click the Add Inventory option.

    The Create new inventory page appears.

  17. In the Name field, enter a name for your inventory. For example, Sample Yum an Apache Inventory.

  18. In the Organization field, click the search button.

    The Select Organization dialog appears.

  19. From the Organization list, select an organization you have created, for example, Sample Yum and Apache Org.

  20. Click Save.

    Note:

    For more information on creating inventories see Setting Up an Inventory

  21. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  22. From the Resources section, click Hosts.

    The Hosts page appears.

  23. Click the Add button.

    The Create New Host page appears.

  24. In the Name field, enter the IP address or host name of the system you are connecting to. The host must be reachable.

  25. In the Inventory field click the search button.

    The Select Inventory page appears.

  26. From the inventory list, select an inventory you have created, for example Sample Yum and Apache Inventory.

  27. Click Save.

    Note:

    Also see Setting Up a Host for information on setting up hosts for an inventory.

  28. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  29. From the Resources section, click Templates.

    The Templates page appears.

  30. Click the Add button.

    A menu appears.

  31. Click the Add job template option.

    The Create New Job Template appears.

  32. In the Name field, enter a name for your job template. For example, Sample Yum or Apache Job.

  33. From the Job Type list, select Run.

  34. From the Inventory list, select an inventory, for example Sample Yum an Apache Inventory.

  35. From the Project list, select a project, for example, Sample Yum and Apache project.

  36. From the Playbook list, select either yum_update.yaml if you want to run a yum update on your host or httpd.yaml if you want to set up an Apache instance on your host.

  37. From the Credentials lists, select a credential, for example Sample Yum and Apache Host Credential.

  38. From the Verbosity list, select 0 (Normal).

  39. If you are running the httpd.yaml playbook, enable Enable Privilege Escalation so the playbook runs with administrator privileges.

  40. Click Save.

  41. Click Launch.

  42. The Output page will appear 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 enables you to 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 do not have to share the same organizations and inventories.

Node Types in Workflow Templates

The nodes in a workflow can be any of the following components:
  • 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 to example_node_2 to the right, this indicates example_node_1 runs immediately before example_node_2.

  • Parent Nodes and Child Nodes

    Continuing with the previous example, if example_node_1 is configured to run immediately before example_node_2, then example_node_1 is said to be the parent node of example_node_2.

    A node can have more than one parent node. For example, you might have a workflow where you configure parent nodes RunSampleYumPlaybook and RunSampleApachePlaybook to run immediately before child node InstallWebApplication. In such a case the Workflow Visualizer shows the lines from each parent node converging directly on child node InstallWebApplication. Also see Convergence Property.

  • 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 are adding should only run if the present node you are 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 are adding should only run if the present node you are 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 are adding should always run, regardless of the final state of the present node you are 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 or not 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): The Any option stipulates this node can run if any of the nodes that converge on this node complete as specified.

    • All: The All option implies this node can only run if all of the nodes that converge on this node complete as specified.

Setting Up a Workflow Template

Note:

For the purposes of the example, it is 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 your target inventory.
  • httpd.yaml: This playbook installs an Apache HTTP server on your target inventory.
For more information on setting up jobs to run the sample playbooks see Setting Up and Running Sample Playbooks
To set up a workflow template, do the following:

  1. Create a job template named RunSampleYumPlaybook that runs the playbook yum_update.yaml against an inventory of servers.

  2. Create a job template named RunSampleApachePlaybook that runs the play book httpd.yaml against an inventory of servers.

  3. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  4. From the Resources section, click Templates.

    The Templates page appears.

  5. Click the Add button.

    A menu appears.

  6. Click the Add workflow template option.

    The Create New Workflow Template page appears.

  7. In the Name field, enter a name for your workflow template. For example, SampleWorkflowTemplate.

    Note:

    The Name field is the only mandatory field on this page. The organization and inventory fields, for instance, do not have to be set at the workflow level.

  8. Click Save.

    The Workflow Visualizer page is displayed in the browser with a Start button.

  9. Click the Start button in the Workflow Visualizer page.

  10. The Add Node dialog appears.

    1. The Node Type drop-down list at the top of the Add Node dialog allows you to select the type of resource to be added as a node. Accept the default choice of Job Template.

    2. Select RunSampleYumPlaybook from the list of available job templates.

    3. Simply accept the default option (Any) from the Convergence drop-down list.

      Note:

      The property is only significant of the node you are adding has more than one parent converging on it.

    4. Optionally enter a Node Alias if you want to the node to be displayed with a particular display name, different to the resource name, in the Workflow Visualizer.

    5. Click Save.

      The Add Node dialog is dismissed.

      The added node appears in the Workflow Visualizer.

  11. Hover your mouse over the newly added node.

    A small toolbar appears within the Workflow Visualizer next to the node.

  12. Click the add (“+”) icon on the toolbar to add another node after the first node.

  13. The Add Node dialog appears.

    1. 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).

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

    3. Select RunSampleApachePlaybook and complete the fields

    4. 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).

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

  15. Click Launch when you are 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 enables you to 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:

  1. Log into Oracle Linux Automation Manager.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Resources section, click Templates.

    The Templates page appears displaying a list of available templates.

  4. Click on the name of the job template you wish to create a schedule for.

    A tabbed view of the job template appears. Initially the Details tab is open.

  5. Switch to the Schedules tab.

  6. 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 Your Schedules in UTC time.

    The application saves your schedules in UTC, a world standard that is not adjusted for daylight saving time. Therefore, to avoid any confusion involving seasonal clock changes, it is best to set and track your schedules in UTC.

  7. Click Save.

    Your saved 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 in your system.

About Execution Environments

Execution environments are portable container images in which your 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.

Execution Environments include the following components:

  • The oraclelinux:8 container image.

  • Oracle Linux Automation Engine based on the Ansible version 2.12 open-source software.

  • Python 3.8

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.1: Private Automation Hub User's Guide.

Note:

While the Builder utility enables you to create custom execution environment, in the case of an issue with the custom execution environment, Oracle support may ask you to revert to the Oracle provided OLAM-EE default image to troubleshoot the problem.

As portable self-contained container images, execution environments allow automation tasks to run consistently across multiple platforms.

The Oracle Linux Automation Manager comes with the following default execution environments:

  • OLAM EE

  • Control Plane Execution Environment

Viewing the Execution Environment Pages

To view an execution environment, do the following:

  1. Log into Oracle Linux Automation Manager.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Administration section, click Execution Environments.

    The Execution Environments page displays a summary table relating to the execution environments available in your 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.1: Private Automation Hub User's Guide.

    • Organization

      The Organization column contains information about which organizations in your system can access the execution environment.

  4. Click on the Name of an execution environment for more details.

    The execution environment will be displayed in a tabbed view with the Details tab active. In addition to the Name, Image and Organization fields, the Details tab contains some additional 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.

        Note:

        It is important to keep the container images up to date to ensure the images have the latest CVE fixes.

  5. 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:

  1. Log into Oracle Linux Automation Manager.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. From the Administration section, click Execution Environments.

  4. Click Add.

    The Create new execution environment page appears.

  5. In the Name field, enter the name of the execution environment.

  6. 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.1: Private Automation Hub User's Guide.

  7. 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 is not present before running the container.

    • Never

      This option stipulates that a container image never pulled before running the container.

      Note:

      It is important to keep the container images up to date to ensure the images have the latest CVE fixes.

  8. Organization

    The Organization field contains information about which organizations in your system can access the execution environment.

  9. Registry credential

    The Registry credential field contains information about which credential your system must use to connect to a container registry. For more information, see Setting Up Container Registry Credentials for your Execution Environment.

  10. 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 enable you to manage your 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, you may wish to create an instance group called mesh_nodes_for_production with nodes to run jobs on your production machines, and another group called mesh_nodes_for_development_machines to run jobs on your 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 Additional Nodes

    The nodes initially available for association with Instance Groups are those you configured for your mesh topology during the installation process. If you require additional 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.1: Installation Guide for more information on configuring nodes for a mesh topology).

  • Nodes Can Belong to More Than One Instance Group

    For example, you may wish to 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.1: Installation Guide).

    However, if required, you can specify instance groups of your choice 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 there is no instance group associated with the job template, Oracle Linux Automation Manager next checks the inventory resource linked to the job. If there is no instance group 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, as well as project and inventory updates and system jobs, but not regular jobs. Control nodes do not have execution capability.

    • execution:

      The execution instance group contains execution nodes. Execution nodes run jobs under ansible-runner with podman 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, as well as how to create groups of your own.

Viewing the Instance Groups Summary

To view the Instance Groups page, do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account.

  2. Display the left navigation menu if it is not already visible by toggling the Global navigation menu button in the top-left corner of the page.

  3. 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 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 currently 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 is currently being used.

  • Action

    The Action column displays an Edit instance group icon that allows you to 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 that will be automatically assigned to the group when new provisioned instances come online.

  • Policy instance percentage

    Minimum percentage of all instances that will be automatically assigned to this group when new provisioned instances come online.

To set the policy properties of an instance group, do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.

  2. In the summary table displayed on the Instance Groups page, go to the row with the group whose policy instance properties you wish to edit.

  3. Click on the Edit instance group icon in the Action column.

    The Edit details page appears.

  4. Enter values of your choice in the properties Policy instance minimum and Policy instance percentage fields.

  5. 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:

  1. Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.

  2. In the summary table displayed on the Instance Groups page, go to the row with the group whose node association you are looking to change.

  3. Click on the group instance name in the Name column.

    A tabbed view of that instance's properties appears. Initially the Details tab is open,

  4. Click on the Instances tab.

    The node instances currently associated with the group are displayed in a table.

  5. To associate more node instances with the group, do the following:

    1. Click on the Associate button.

      The Select Instances dialog appears displaying available node instances.

    2. Select the check boxes next to the nodes you wish to associate with the group instance.

    3. Click Save.

      The Instances page will be displayed and the nodes you selected appear in the list on the page.

  6. To disassociate nodes from the current group instance, do the following:
    1. Select the check box next to each host you wish to disassociate from the current group and click the Disassociate button.

      A dialog will ask you to confirm your actions.

    2. Confirm your actions if you are 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.

Modifying Node Instance Properties

The following procedures show you how to modify 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 modify a node instance's capacity, do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.

  2. In the summary table displayed on the Instance Groups page, go to the row with the group associated with the node you wish to edit.

  3. Click on the group instance name in the Name column.

    A tabbed view of that instance's properties appears. Initially the Details tab is open,

  4. Click on the Instances tab.

    The node instances associated with the group are displayed in a table.

  5. Go to the row with the node instance you wish to modify.

  6. To adjust the Capacity, drag the slider control in the Capacity Adjustment column to the value of your choice.

    Note:

    • The change is saved automatically. There is no Save button.
    • Consider whether the new capacity setting is suitable for other instance groups the node might belong to.

The enable/disable setting enables you to control whether or not a node instance is available for jobs to be assigned to it. For example, you might need to temporarily disable one of your node instances for maintenance. To change a node instance's enable/disable setting, do the following:

  1. Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.

  2. In the summary table displayed on the Instance Groups page, go to the row with the group associated with the node you wish to edit.

  3. Click on the group instance name in the Name column.

    A tabbed view of that instance's properties appears. Initially the Details tab is open,

  4. Click on the Instances tab.

    The node instances associated with the group are displayed in a table.

  5. Go to the row with the node instance you wish to modify.

  6. 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. There is no Save button.
    • 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:

  1. Log into Oracle Linux Automation Manager with an administrator user account and navigate to the Instance Groups page.

  2. Click the Add button.

    A menu appears.

  3. Click the Add instance group option.

    The Create new instance group appears.

  4. In the Name field, enter a name for your instance group. For example, NodesForDataCentre1.

  5. 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 that will be automatically assigned to the group when new provisioned instances come online.

    • Policy instance percentage:

      Minimum percentage of all instances that will be automatically assigned to this group when new provisioned instances come online

  6. Click Save.

    The newly created instance group is displayed in a tabbed view with the Details tab active.

  7. Click the Instances tab to switch to the Instances tab.

    The node instances currently associated with the group are displayed in a table.

  8. To associate more node instances with the group, click on the Associate button.

    The Select Instances dialog appears displaying available node instances.

  9. Select the check boxes next to the nodes you wish 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.