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 Oracle Linux Automation Engine or Oracle Linux Automation Manager.

Objectives

In this tutorial, 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 account's credentials and OCID information

Deploy Oracle Linux Automation Manager

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

Open a terminal on the Luna Desktop.

Clone the linux-virt-labs GitHub project.

git clone https://github.com/oracle-devrel/linux-virt-labs.git

Change into the working directory.
```
cd linux-virt-labs/olam
```

Install the required collections.

ansible-galaxy collection install -r requirements.yml

Update the Oracle Linux instance configuration.

cat << EOF | tee instances.yml > /dev/null
compute_instances:
  1:
    instance_name: "olam-node"
    type: "control"
  2:
    instance_name: "git-server"
    type: "server"
EOF

Deploy the lab environment.
```
ansible-playbook create_instance.yml -e ansible_python_interpreter="/usr/bin/python3.6" -e "@instances.yml" -e olam_single_host=true -e use_git=true
```
The free lab environment requires the extra variable ansible_python_interpreter because it installs the RPM package for the Oracle Cloud Infrastructure SDK for Python. The location for this package's installation is under the python3.6 modules.
The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.
Important: Wait for the playbook to run successfully and reach the pause task. The Oracle Linux Automation Manager installation is complete at this stage of the playbook, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys.

Create a Playbook

Open a new terminal window.
Set a variable to the remote git-server instance.
```
export REMOTE=<ip_address_of_instance>
```
Create a project directory.
```
mkdir ~/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 > ~/myproject/requirements.yml 
---
collections:
  - name: oracle.oci
  - name: community.general
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 the collections GitHub repository.

cat << EOF > ~/myproject/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

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 > ~/myproject/get_namespace.yml
---
- name: Get namespace name
  hosts: localhost
  
  tasks:
  
  - name: get namespace
    oracle.oci.oci_object_storage_namespace_facts:
    register: output
  
  - name: print namespace
    ansible.builtin.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 configuration steps.
1. Set the default branch name used when initializing a project.
```
git config --global init.defaultBranch main
```
2. Set your identity.
  The email and name are examples within this tutorial. Use your email and name when working on your projects, as this information gets immutably baked into each commit.
```
git config --global user.email johndoe@example.com
git config --global user.name "John Doe"
```
3. Change into the project's working directory.
```
cd ~/myproject
```
4. 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.
A remote repository 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@$REMOTE "git init -b main --bare /git-server/repos/myproject.git"
```
The -b option ensures the initialization of the remote repository using a branch called main.
Accept the ECDSA key fingerprint by typing yes.
Add the new remote repository connection record.
Adding the remote connection to the local repository allows you to use it as a named shortcut in Git commands.
```
git remote add origin git@$REMOTE:/git-server/repos/myproject.git
```
The path after the colon is the repository's directory location on the remote Git server.
Verify the newly added connection record.
```
git remote -v
```
The output shows the connection record origin pointing to the remote Git repository location for both the git fetch and git push commands.
Push the local repository changes to the remote repository.
```
git push origin main
```
Using the myproject source within an Oracle Linux Automation Manager Project is now possible.

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 new terminal window and configure an SSH tunnel to the olam-node instance.
```
ssh -L 8444:localhost:443 oracle@<ip_address_of_instance>
```
Open a web browser and enter the URL.
```
https://localhost:8444
```
Note: Approve the security warning based on the browser used. For the Chrome browser, 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 the Resources section 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 enable the downloading of roles and collections using the ansible-galaxy command.
- Galaxy Server URL: https://galaxy.ansible.com
Review the entries and click the Save button.
Click Organizations under the Access section 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 your OCI configuration information.
Open a new terminal window.
Display the contents of the 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.
Get the contents of your OCI user's API private key.
On the free lab environment, you can run cat ~/.oci/oci.key to get this information and then copy the entire output, including the BEGIN and END lines.
Paste the key into the Private User Key field 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 a localhost network connection when using Oracle Linux Automation Engine to interact with 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.
Enter the Git server's username.
- Username: git
Copy and paste the contents of your Git server's private key into the SCM Private Key field.
The free lab environment uses the default ~/.ssh/id_rsa file.
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 (2.2)
- Source Control Credential Type: Git
The page refreshes, requesting the Type Details.
- Source Control URL: git@<ip_address_of_instance>:/git-server/repos/myproject.git
- Source Control Branch: main
- Source Control Credential: Git Server
The free lab environment uses the git-server IP address in the Source Control URL field.
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 or select the required values.
- Name: My Template
- Job Type: Run
- Inventory: My Local Inventory
- Project: My Project
- Execution Environment: OLAM EE (2.2)
- Playbook: get_namespace.yml
Select the credentials.
When selecting the Credentials, a Select Credentials pop-up dialog will appear. Choose Oracle Cloud Infrastructure from the Selected Category drop-down list of values to display credentials of that type.
Select My OCI Credentials and then click the Select button.
Review the Job Template entries.
Scroll down the page 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 template's output, including the OCI tenancy's namespace. You can click the Reload output link to refresh the output panel if necessary.

Next Steps

The output showing the namespace confirms you have a working configuration and project demonstrating how to use playbooks leveraging the Oracle Cloud Infrastructure Ansible Collection. Experiment further with the collection to deploy instances and other resources to your tenancy.