Oracle Cloud Infrastructure Documentation

Getting Started

This topic discusses how to get started using the Oracle Cloud Infrastructure (OCI) Ansible collection. The OCI Ansible 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 OCI, ensure that you meet the prerequisites, then install the Ansible 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 OCI Ansible collection and its dependencies, and preconfigures the required authorization.

Both Ansible and our Ansible collection also come preinstalled and preauthenticated 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 Collection with Yum

If you're running Oracle Linux 7 or Oracle Linux 8, you can use yum to install the Oracle Cloud Infrastructure Ansible collection RPM.

The Ansible collection RPM installs the OCI Ansible 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.

Use one of the following commands to enable the Oracle Linux developer repository and install the Ansible collection RPM, depending on your Oracle Linux version.

Oracle Linux 7:

yum install -y oci-ansible-collection --enablerepo ol7_developer --enablerepo ol7_developer_EPEL

Oracle Linux 8:

yum install -y oci-ansible-collection --enablerepo ol8_developer --enablerepo ol8_developer_EPEL

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

Test the Installation

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

If you're using Oracle Linux 7, use the following command to test your installation:

ansible-3 localhost -m oracle.oci.oci_object_storage_namespace_facts

If you're using Oracle Linux 8, use the following command to test your installation:

ansible localhost -m oracle.oci.oci_object_storage_namespace_facts

Manual Installation

Installing the Oracle Cloud Infrastructure Ansible Collection

Install the OCI 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 Playbooks

Sample playbooks are available in the Oracle Cloud Infrastructure Ansible collection GitHub project. The samples library is updated regularly with the addition of new samples. See Example 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 docs.oracle.com and 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.