5 Setting Up Resources

This chapter describes setting up resources which are the primary configuration touch points between Oracle Linux Automation Manager and Oracle Linux Automation Engine playbooks and inventory. These resources are projects, inventories, credentials, job templates, and workflow templates.

Setting Up Projects

A Project is a resource that represent 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.

2. Expand the left side menu and from the Resources section, click Projects.

   The Projects page appears.

3. Click the Plus icon.

   The New Projects page appears.

4. In the Name field, enter a name.

5. From the Organization List, select an organization, for example, Organization 1.

6. From the SCM Type list, select one of the following:

   • If you want to use a playbook located on the machine hosting Oracle Linux Automation Manager, select Manual. See Accessing a Local Oracle Linux Automation Engine Playbook for more information.

   • If you want to use a playbook from a remote repository such as from Git, select Git. Go to Accessing a Remote Oracle Linux Automation Engine Playbook on Git for information about setting up source details and credentials.

7. Click Save.

Accessing a Local Oracle Linux Automation Engine Playbook

To access a local playbook, do the following:

1. Create a directory where to store your Oracle Linux Automation Engine playbooks. The default location is /var/lib/ol-automation-manager/projects.

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

3. 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 Oracle Linux Automation Engine Playbook on Git

Git is a distributed version control system containing repositories where you can store Oracle Linux Automation Engine 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-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 SCM URL field, enter a URL to the SCM repository.

4. If you need to specify an SCM branch, tag, or commit in the SCM Branch/Tag/Commit field, enter a branch, tags, or commit hash.

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

6. If the Git repository you specified is private and requires credentials to access, from the SCM Credential list, select a credential. For more information about setting up credentials, see Setting Up Credentials.

7. If Oracle Linux Automation Manager requires access to the Git repository through a proxy, expand the left side menu and from the Administration section, click Settings.

   The Settings page appears.

8. Click Jobs.

   The Jobs page appears.

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

10. Click Save.

    Note:

    If your Oracle Linux Automation Engine 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

To set up an inventory, do the following:

1. Log into Oracle Linux Automation Manager.

2. Expand the navigation menu, and from the Resources section, click Inventories.

   The Inventories page appears.

3. Click the Plus icon.

4. Click Inventory.

   The New Inventory page appears.

5. In the Name field, enter a name.

6. From the Organization list, select an organization.

7. In the Variables field, enter YAML or JSON code if you want to specify any inventory variables.

8. Click Save.

Setting Up a Host

To set up a host, do the following:

1. From an inventory, click the Hosts button.

   The Hosts page appears

2. Click the Plus icon.

   The Create Host page appears.

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

4. Click Save.

5. To create additional hosts from this screen, click the Plus icon and repeat steps 3 and 4.

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. From an inventory, click the Hosts button.

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

2. Select the checkbox beside one or more hosts on the left side.

   The Run Command button becomes available.

3. Click the Run Commands button.

   The Execute Command page appears.

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

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

6. From the Machine Credentials list, select the credentials for the machines. See Setting Up Credentials for information about setting up credentials.

7. Click Launch.

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

Setting Up Credentials

The following sections provide information about setting up various kinds of credentials on Oracle Linux Automation Manager.

Setting Up Git Credentials

To set up credentials Git credentials, do the following:

1. Log into Oracle Linux Automation Manager.

2. Expand the navigation menu, and from the Resources section, click Credentials.

   The Credentials page appears.

3. Click the Plus icon.

   The New Credentials page appears.

4. In the Name field, enter the name of the credential.

5. From the Organization lists, select an organization.

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

7. In the UserName field, enter the username, if required.

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

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

10. From the Private Key Passphrase list, enter a passphrase. (If you have set up a passphrase for SSH authentication).

11. Click Save.

Setting Up Inventory Machine Credentials

To set up inventory machine credential, do the following:

1. Log into Oracle Linux Automation Manager.

2. Expand the navigation menu, and from the Resources section, click Credentials.

   The Credentials page appears.

3. Click the Plus icon.

   The New Credentials page appears.

4. In the Name field, enter the name of the credential.

5. From the Organization lists, select an organization.

6. From the Credential Type list, select Machine.

7. In the UserName field, enter the username, if required.

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

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

10. In the SSH Private Key field, enter the SSH private key you set up on the host running Oracle Linux Automation Engine. (If you are using SSH authentication).

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

12. From the Private Key Passphrase list, enter a passphrase. (If you have set up a passphrase for SSH authentication).

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

14. From the Privilege Escalation Method list, select an escalation methods if the playbooks you run in the machine require an escalation method, for example, sudo.

15. In the Privilege Escalation UserName field, enter the username, if required.

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

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

18. Click Save.

Setting Up Credentials Permissions

To specify which users have permission to use a credential, do the following:

1. Log into Oracle Linux Automation Manager.

2. Expand the navigation menu, and from the Resources section, click Credentials.

   The Credentials page appears.

3. Select an existing credential.

   The Edit Credential page appears.

4. Click the Permissions button.

   The Edit Credential / Permissions page appears.

5. Click the Plus icon.

   The Add Users / Teams page appears.

6. Click the Users button.

   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.

7. From the lefthand column, select the checkbox beside each user you want to provide permission to use the credential.

8. Click the Teams button.

   A list of available teams appears.

9. From the lefthand column, select the checkbox beside each team you want to provide permission to use the credential.

10. Click Save.

Setting Up Job Templates

The following sections provide information about setting up job templates and workflow templates.

Setting Up a Job Template

Job Templates allow you to run Oracle Linux Automation Engine 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.

2. Expand the navigation menu, and from the Resources section, click Templates.

   The Templates page appears.

3. Click the Plus icon.

4. Select Job Template.

   The New Job Template page appears.

5. Click the Details button.

6. In the Name field, enter a name.

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

   • Run: Runs the Oracle Linux Automation Engine playbook.

   • Check: Checks that the Oracle Linux Automation Engine playbook can run without errors.

8. From the Inventory list, select an inventory.

9. From the Project list, select a project. For example, you can select a project that uses the sample Yum Oracle Linux Automation Engine playbook that runs a yum update or creates an HTTPD on your inventory.

10. From the Playbook list, select a playbook. For example, if you are using the sample Yum Oracle Linux Automation Engine playbook, select yum_update.yaml.

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

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

13. In the Limit field, enter the hostname or IP addresses that further limits the hosts specified in the inventory where the job can run, if required.

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

15. In the Job Tags field, enter one or more job tags. Tags allow you have run portions of large playbook that contain tags. You can specify more than one tag using commas to separate each.

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

17. In the Labels field, enter a label that describes the job. You can use these labels in various Oracle Linux Automation Manager views to sort different jobs.

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

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

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

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

22. If you want to display a dialog that contains prompts for specific fields when launching a Oracle Linux Automation Engine playbook, select the Prompt On Launch checkbox above the fields you want to display.

23. Check the following options if required:

    • Enable Privilege Escalation: The playbook runs with administrator privileges.

    • Enable Provisioning Callbacks: Creates a provisioning callback URL so a host can request a configuration update Oracle Linux Automation Manager using this job template.

    • Enable Webhook: The playbook enables webhooks.

    • Enable Concurrent Jobs: Oracle Linux Automation Manager can run multiple instances of the job template at the same time.

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

24. In the Extra Variables field, enter YAML or JSON code if you want to pass any variables to the Oracle Linux Automation Engine playbook.

25. 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 Inventory Machine Credentials.

4. Expand the left side menu and from the Resources section, click Projects.

   The Projects page appears.

5. Click the Plus icon.

   The New Projects page appears.

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

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

8. From the SCM Type list, select Manual.

   In the Project Base Path field shows the default project base path located at /var/lib/ol-automation-manager/projects.

9. From the Playbook Directory list, select demo_bundled.

10. Click Save.

11. Expand the left side menu and from the Resources section, click Inventory.

    The Inventories page appears.

12. Click the Plus icon.

    The New Inventory page appears.

13. In the Name field, enter a name, for example Sample Yum an Apache Inventory.

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

15. Click Save.

16. Click Hosts.

17. Click the Plus icon.

    The Create Host page appears.

18. In the Host Name field, enter a hostname or IP address. The host must be reachable.

19. Click Save.

20. Expand the navigation menu, and from the Resources section, click Templates.

    The Templates page appears.

21. Click the Plus icon.

22. Select Job Template.

    The New Job Template page appears.

23. Click the Details button.

24. In the Name field, enter a name, for example Sample Yum or Apache Job.

25. From the Job Type list, select Run.

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

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

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

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

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

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

32. Click Save.

33. Click Launch.