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.
Set the default branch name used when initializing a project.
git config --global init.defaultBranch main
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"
Change into the project's working directory.
cd ~/myproject
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
andgit 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 Passwordadmin
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
- Name:
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.
- Name:
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.
- Name:
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.
- Name:
Enter the Git server's username.
- Username:
git
- Username:
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.
- Name:
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
- Name:
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.