Getting Started with Oracle Cloud Infrastructure and Ansible

This topic discusses how to get started using the Oracle Cloud Infrastructure Ansible modules collection. The Oracle Cloud Infrastructure Ansible modules collection replaces our legacy Ansible modules.

Note

If you currently use our legacy Ansible modules and would like to start using collections, refer to our migration guide.

To start using Ansible with Oracle Cloud Infrastructure, ensure that you meet the prerequisites, then install the Ansible modules collection using yum or manually.

Tip

You can use Resource Manager to preinstall the Oracle Cloud Development Kit on a Compute instance in your compartment. The Oracle Cloud Development Kit includes Ansible, the Ansible modules collection and its dependencies, and preconfigures the required authorization.

Both Ansible and our Ansible modules collection also come pre-installed and pre-authenticated on Cloud Shell.

Prerequisites for Using Ansible with Oracle Cloud Infrastructure

  • You must have an Oracle Cloud Infrastructure account.
  • You must have a user in that account in a security group with a policy that grants necessary permissions for working with resources in the account compartments. For guidance, see How Policies Work.
  • You must have the necessary credentials and OCID information.

Installing the Ansible Modules Collection with yum

You can use yum to install the Oracle Cloud Infrastructure Ansible modules collection RPM.

The Ansible modules collection RPM installs the Oracle Cloud Infrastructure Ansible modules collection and its required dependencies: the OCI SDK for Python and Ansible.

Note

This installation uses Python version 3.6 and Ansible version 2.9 or later.

The following example shows how to use yum to install the Ansible modules collection RPM:

yum -y install oraclelinux-developer-release-el7 && sudo yum install oci-ansible-collection

After installing the RPM, you must configure the SDK and CLI configuration file as explained in Configuring Authentication.

To test the installation of the RPM and configuration of the SDK, you can run a sample playbook. For example:

ansible-playbook-3 /usr/share/doc/oci-ansible-collection-<version>/samples/object_storage/get_namespace/sample.yaml

Manual Installation

Installing the Oracle Cloud Infrastructure Ansible Module Collection

Install the Oracle Cloud Infrastructure Ansible collection from Ansible Galaxy by using the following command:

$ ansible-galaxy collection install oracle.oci

If you've already installed the collection, you can update its modules to the latest version by adding the --force flag to the command. For example:

$ ansible-galaxy collection install --force oracle.oci

Sample Ansible Modules

Sample modules are available in the Oracle Cloud Infrastructure Ansible collection GitHub project. The samples library is updated regularly with the addition of new samples. See Sample Ansible Playbooks for more information.

Writing a Sample Playbook

After your installation is complete, or if you're using the Cloud Shell, you can write a sample playbook that uses Ansible modules. Following is an example playbook (named list_buckets.yml) that uses the oci_object_storage_bucket_facts module to fetch facts pertaining to the buckets in your compartment.

---
- name : List summary of existing buckets in OCI object storage
  collections:
    - oracle.oci
  connection: local
  hosts: localhost
  tasks:
    - name: List bucket facts
      oci_object_storage_bucket_facts:
         namespace_name: '<yournamespace>'
         compartment_id: '<yourcompartmentocid>'
      register: result
    - name: Dump result
      debug: 
        msg: '{{result}}'

Executing the Playbook

Execute the Ansible playbook using Python by invoking this command:

$ ansible-playbook list_buckets.yml

How to Obtain Module Documentation

Detailed information about using our Ansible modules is available on readthedocs.io.

To obtain access to detailed information about using Ansible modules in the CLI, use the ansible-doc command on the module's name. For example, to get the documentation for the oci_object_storage_bucket_facts module, execute the following command:

$ ansible-doc oracle.oci.oci_object_storage_bucket_facts

Configuring Authentication

When creating and configuring Oracle Cloud Infrastructure resources, Ansible modules use authentication information that is outlined in the SDK and CLI Configuration File.

Caution

User Credentials that are referenced in Oracle Cloud Infrastructure SDK configuration files grant access to Oracle Cloud Infrastructure resources. Therefore, it is important to secure the credentials to prevent unauthorized access to these resources. To secure the credentials on the controller node where your Ansible playbooks run, follow guidelines outlined in the document Securing IAM (see section entitled "IAM Credentials").

Ansible modules permit you to override authentication information specified in the SDK configuration file by using module options and environment variables. Documentation for authentication overrides is provided internally, as described in How to Obtain Module Documentation. However, using environment variables and Ansible module options to override authentication information must be avoided in production scenarios.

We recommend using Oracle Cloud Infrastructure SDK configuration files to specify authentication information. To support multiple users, use the "profiles" feature in the SDK configuration file. When distributing roles that use Ansible modules, ensure that no IAM credentials are included with the roles.