Use OCI Ansible Collection with Oracle Linux Automation Manager

Introduction

The Oracle Cloud Infrastructure (OCI) Ansible Collection provides an easy way to provision and manage resources in the Oracle Cloud using Ansible.

This tutorial shows how to use this collection in Oracle Linux Automation Manager and interacts with an Oracle Cloud tenancy.

Objectives

In this lab, you'll learn how to:

Create a playbook that uses the OCI Ansible Collection
Configure credentials for Ansible Galaxy
Add the Oracle Cloud Infrastructure credential
Create a Job Template
Run the Job

Prerequisites

A system with Oracle Linux Automation Manager installed
Access to a git repository
An Oracle Cloud Infrastructure (OCI) account
A user in the OCI account with permission to work with resources in a compartment
Access to that accounts credentials and OCID information

For details on installing Oracle Linux Automation Manager, see the Oracle Linux Automation Manager Installation Guide .

Create a Playbook

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

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

Open a terminal on the free lab desktop.
Create the project directory.
```
mkdir ~/myproject
```
```
cd ~/myproject
```

Create a requirements file.

Oracle Linux Automation Engine uses the requirements file to pull any required collections or roles into the project at runtime.

cat << EOF > requirements.yml 
---
collections:
  - name: https://github.com/oracle/oci-ansible-collection.git
    type: git
    version: master
  - name: https://github.com/ansible-collections/community.general.git
    type: git
    version: main
EOF

Note: For versions of the Oracle Linux Automation Engine >= 2.13.9, you can configure the requirements file to pull the collection directly from Ansible Galaxy.
cat << EOF > requirements.yml 
---
collections:
  - name: oracle.oci
  - name: community.general
EOF

Create a playbook.

This playbook queries the object storage namespace for the Oracle Cloud Infrastructure tenancy. We'll configure the tenancy details later in the Oracle Linux Automation Manager WebUI.

cat << EOF > get_namespace.yml
---
- name: get namespace name
  hosts: localhost
  collections:
    - oracle.oci
  tasks:
    - name: get namespace
      oracle.oci.oci_object_storage_namespace_facts:
      register: output
    - name: print namespace
      debug:
        msg: "{{ output }}"
EOF

Add the Project to Source Control

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

Create and initialize the remote Git repository.

The free lab environment provides a Git server where we'll push the playbook project along with all the other dependencies.

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

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

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

Accept the ECDSA key fingerprint to continue if a prompt appears.

Example Output:

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

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

Verify the newly added connection record.

git remote -v

Example Output:

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

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

Push local repository changes to the remote repository.

git push origin main

Example Output

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

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

Create Ansible Galaxy Credentials

These credentials allow Oracle Linux Automation Manager to pull the OCI Ansible Collection from the public Ansible Galaxy Hub.

Open a terminal from the Luna Desktop and configure an SSH tunnel to the deployed Oracle Linux Automation Manager instance.
```
ssh -L 8444:localhost:443 oracle@<hostname or ip address>
```
In the free lab environment, use the IP address of the ol-node VM as it runs the Oracle Linux Automation Manager deployment.
Open a web browser and enter the URL.
```
https://localhost:8444
```
Note: Approve the security warning based on the browser used. For Chrome, click the Advanced button and then the Proceed to localhost (unsafe) link.
Log in to the Oracle Linux Automation Manager WebUI. Use the Username admin and the Password admin created during the automated deployment.
The WebUI displays after a successful login.
Click Credentials under Resources in the navigation menu.
Click the Add button.
Enter or select the following values in the specific fields.
For fields with a search or list of values, we can start typing the requested value and then select it.
- Name: My Ansible Galaxy
- Organization: Default
- Credential Type: Ansible Galaxy/Automation Hub API Token
Oracle Linux Automation Manager uses the Ansible Galaxy credentials to set the order to download roles/collections using the ansible-galaxy command.
- Galaxy Server URL: https://galaxy.ansible.com
Review the entries and click the Save button.
Click Organizations under Access in the navigation menu.
Assigning the Ansible Galaxy credential within the Organization enables the download of the Oracle Linux Infrastructure Ansible Collection from within the git project.
Click the Default organization and click the Edit button.
Select the My Ansible Galaxy credential in the Galaxy Credentials field and click the Select button.
Review and click the Save button.

Create OCI Credentials

The OCI credentials provide Oracle Linux Automation Manager information about the specific OCI tenancy.

Click Credentials in the navigation menu.
Click the Add button.
Enter or select the following values in the specific fields.
- Name: My OCI Credentials
- Organization: Default
- Credential Type: Oracle Cloud Infrastructure
The page refreshes and requests information specific to the free lab environments tenancy. Gather these details using a terminal on the free lab environment desktop.
Open a new terminal from the Luna Desktop.
Display the contents of the free lab environment OCI configuration file.
```
cat ~/.oci/config
```
Use the values shown in the terminal and match them to the specific fields of the OCI credential in the Oracle Linux Automation Manager WebUI.
Use the icon next to each field to show the value of the paste.
Copy and paste the OCI user's private key.
1. Run the cat ~/.oci/oci.key command in the terminal.
2. Copy the output, including the line at the beginning and end that starts with -----.
3. Paste the data into the Private User Key value within the Oracle Linux Automation Manager WebUI.
Review and click the Save button.

If you need to edit these values later, they will appear encrypted in the WebUI. Therefore, to make changes, click the Replace icon next to the specific field and add the new value for the field. Repeat as needed and then click the Save button when done making changes.

Create an Inventory

Click Inventories in the navigation menu.
Click the Add button and select Add inventory from the drop-down list of values.
Enter or select the following values in the specific fields.
- Name: My Local Inventory
- Instance Groups: controlplane
The Oracle Cloud Infrastructure Ansible Collection uses localhost when connecting with Oracle Linux Automation Engine to the OCI tenancy.
Review and click the Save button.

Add Source Control Credential

Click Credentials in the navigation menu.
Click the Add. button.
Enter or select the following values in the specific fields.
- Name: Git Server
- Credential Type: Source Control
The page refreshes, requesting the Type Details.
- Username: git
- SCM Private Key:
Copy and paste the contents of the ~/.ssh/id_rsa file from the free lab environment desktop into the SCM Private Key field.
Review and click the Save button.

Create a Project

Click Projects in the navigation menu.
Click the Add button.
Enter or select the following values in the specific fields.
- Name: My Project
- Execution Environment: OLAM EE (latest)
- Source Control Credential Type: Git
The page refreshes, requesting the Type Details.
- Source Control URL: git@<hostname or ip address of git server>:/git-server/repos/myproject.git
- Source Control Credential: Git Server
Replace the hostname or IP address in the Source Control URL with the actual git server in the free lab environment.
Review and click the Save button.
Review the project sync status.
After project creation, the project will display its status in the Details summary as the sync begins. The status transitions from Running to Successful if the configuration is correct and the git server is reachable.

Create Job Template

Click Templates in the navigation menu.
Click the Add button and select Add job template from the drop-down list of values.
Enter the required values.
- Name: My Template
- Job Type: Run
- Inventory: My Local Inventory
- Project: My Project
- Execution Environment: OLAM EE (latest)
- Playbook: get_namespace.yml
- Credentials: My OCI Credentials
When selecting the Credentials for the Template, first choose the category of Oracle Cloud Infrastructure.
Review, scroll down, and click the Save button.
Launch the template.
Launch a job from the template summary page by clicking the Launch button.
If successful, the job launches and displays the output from the template. The standard output shows the playbook running and outputs the name of the namespace for the OCI tenancy.

Summary

This output confirms you have a working project and configuration for running playbooks using the Oracle Cloud Infrastructure Ansible Collection.

For More Information

Oracle Linux Automation Manager Documentation
Oracle Linux Automation Manager Training
Oracle Linux Training Station