Oracle Cloud Infrastructure Documentation

Getting Started with Ansible for Oracle Cloud Infrastructure

This topic discusses how to get started with downloading and using Ansible with the Oracle Cloud Infrastructure. There are four initial steps for getting started with Ansible:

  • Ensure that you have all of the prerequisites
  • Download and install the Oracle Cloud Infrastructure Python SDK
  • Download and install Ansible
  • Download and install the Ansible modules for Oracle Cloud Infrastructure

Prerequisites for Using Ansible for Oracle Cloud Infrastructure

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

Installing the Oracle Cloud Infrastructure Python SDK

  1. Download and install the Python SDK by following instructions in the topic, Python SDK. For additional guidance, see Downloading and Installing the SDK.

  2. After installing the Python SDK, you must configure it using instructions in the topic Configuring the SDK.

Installing and Configuring Ansible

Installing Oracle Cloud Infrastructure Ansible Modules on an Oracle Linux image

Oracle Cloud Infrastructure Ansible Modules come pre-installed on the Oracle Cloud Developer image.

Note

For more information on Oracle Cloud Infrastructure-provided images, see Oracle-Provided Images.

 

 

To install Oracle Cloud Infrastructure Ansible Modules on an Oracle Linux image:

  1. $ yum install oci-ansible-modules

Installing Oracle Cloud Infrastructure Ansible Modules on a non-Oracle Linux image

  1. $ git clone https://github.com/oracle/oci-ansible-modules.git
  2. $ cd oci-ansible-modules
  3. Run one of the following commands:

    1. If Ansible is installed as a user:

      $ ./install.py

    2. If Ansible is installed as root:
      $ sudo ./install.py

 

Sample Ansible Modules

Sample modules are available in the Oracle Cloud Infrastructure Ansible Module GitHub project. The samples library is updated regularly with the addition of new samples. You can access the samples at https://github.com/oracle/oci-ansible-modules.

Writing a Sample Playbook

You can now write a sample playbook that uses Ansible modules. Following is an example playbook (named list_buckets.yml) that uses the oci_bucket_facts module to fetch all of the facts pertaining to all of the buckets in your compartment.

---
- name : List summary of existing buckets in OCI object storage
  connection: local
  hosts: localhost
  tasks:
    - name: List bucket facts
      oci_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

To obtain access to detailed information about using Ansible modules in the CLI, including documentation of a module's configurable options, samples, return values, and so forth, use the ansible-doc command on the module's name. For example, to get the documentation for the oci_bucket_facts module, execute the following command:

$ ansible-doc oci_bucket_facts

Documentation of the Oracle Cloud Infrastructure Ansible modules is also available in the Cloud Modules page of the Oracle Cloud Infrastructure Ansible Modules site.

Configuring Authentication

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

Warning

IAM credentials that are referenced in Oracle Cloud Infrastructure SDK configuration files grant access to Oracle Cloud Infrastructure resources. Because of this, 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 this is provided internally, as described in the preceding section, 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. Use the "profiles" feature in the SDK configuration file to support different users. When distributing roles that use Ansible modules, ensure that no IAM credentials are included with the roles.

For More Information