Using the Ansible Dynamic Inventory Plugin

Ansible inventory plugins allow you to define the data sources used to compile an inventory of hosts that Ansible uses to target tasks. These data sources are accessed by using either the -i /path/to/file or the -i 'host1, host2' command line parameters, or from other configuration sources.

Note

For more information on inventory plugins, see the official Ansible documentation.

Enabling the Oracle Cloud Infrastructure Inventory Plugin for Ansible

The Oracle Cloud Infrastructure inventory plugin, like most inventory plugins shipped with Ansible, is disabled by default. Plugins must be enabled in your ansible.cfg file to function.

Enable the OCI inventory plugin by adding it to your ansible.cfg file. For example:

[inventory]
enable_plugins = oracle.oci.oci

If you still use our legacy Ansible modules, your ansible.cfg file should contain the following entry instead:

[inventory]
enable_plugins = oci

Using the OCI Inventory Plugin for Ansible

The only requirement for using an inventory plugin after it is enabled is to provide an inventory source to parse.

To start using an inventory plugin with a YAML configuration source, create a file with the accepted filename schema for the plugin, then add plugin: plugin_name. The OCI inventory plugin requires a *.oci filename extension.

The minimum inventory source file needed to run the OCI inventory plugin looks like this, for example:

# demo.oci.yml
plugin: oracle.oci.oci
 
# Optional fields to specify oci connection config:
config_file: ~/.oci/config
config_profile: DEFAULT

You can run the inventory with this command:

ansible-inventory -i demo.oci.yml --graph

This will produce output similar to the following:

@all:
  |--@oci:
  |  |--compute_instance1
  |  |--compute_instance2
  |–@ungrouped:

You can add custom inventory plugins to your plugin path and set the default inventory path to simplify your commands. Add the default inventory path to the [defaults] section of your ansible.cfg file, or use the ANSIBLE_INVENTORY environment variable to point your inventory sources. Now running `ansible-inventory --graph` yields the same output as when you pass your YAML configuration sources directly.

Inventory plugins normally only execute at the start of a run, before playbooks, plays, and roles are loaded. You can ‘re-execute’ a plugin by using the meta: refresh_inventory task, which clears out the existing inventory and rebuilds it.

Using Dynamic Groups

You can create dynamic groups using host variables with the constructed keyed_groups option. The option groups can also be used to create groups and create and modify host variables.

For example:

# demo.oci.yml
plugin: oracle.oci.oci
regions:
  - us-phoenix-1
  - us-ashburn-1
keyed_groups:
  # add hosts to tag_Name_value groups for each oci host's tags.Name variable
  - key: tags.Name
    prefix: tag_Name_
groups:
  # add hosts to the group development if any of the dictionary's keys or values is the word 'devel'
  development: "'devel' in (tags|list)"

This example produces output similar to the following:

@all:
  |--@oci:
  |  |--compute_instance1
  |  |--compute_instance2
  |  |--...
  |--@development:
  |  |--compute_instance1
  |  |--compute_instance2
  |--@tag_Name_Dev_Instance:
  |  |--compute_instance1
  |--@tag_Name_Test_Server:
  |  |--compute_instance2
  |--@ungrouped

If a host does not have the variables specified in the configuration (such as tags.Name, tags, private_ip_address), the host is not added to groups other than those that the inventory plugin creates and the ansible_host host variable is not modified.

Caching

Caching can be enabled to speed lookups. You can set caching options for an individual YAML configuration source or for multiple inventory sources using environment variables or Ansible configuration files. If you enable caching for an inventory plugin without providing inventory-specific caching options, the inventory plugin uses fact-caching options.

Here is an example of enabling caching for an individual YAML configuration file:

# demo.oci.yml
plugin: oracle.oci.oci
cache: yes
cache_plugin: jsonfile
cache_timeout: 7200
cache_connection: /tmp/oci_inventory
cache_prefix: oci

Database Hosts

Database nodes can be now be fetched by setting the option fetch_db_hosts. Database nodes are servers running database software. For example:

# demo.oci.yml

# DB Hosts
plugin: oracle.oci.oci
fetch_db_hosts: true

Examples

Here are some examples of options that can be used in the inventory source file:

# Fetch all hosts
plugin: oracle.oci.oci
 
# OCI Config information
config_file: ~/.oci/config
config_profile: DEFAULT
 
# Optional fields
# ----------------------------
# Example select regions
regions:
- us-ashburn-1
- us-phoenix-1
 
# Enable threads to speedup lookup
enable_parallel_processing: yes
 
# Select compartment by ocid or name
compartments:
- compartment_ocid: ocid1.compartment.oc1..<compartment_OCID>
   fetch_hosts_from_subcompartments: false
- compartment_name: "<compartment_name>"
   parent_compartment_ocid: ocid1.tenancy.oc1..<compartment_OCID>
 
# Example filtering using hostname IP
hostnames:
- "10.145.214.11"
 
# Example group results by key
keyed_groups:
- key: availability_domain
 
# Example using filters
filters:
- availability_domain: "IwGV:US-ASHBURN-AD-3"
- display_name: "instance20190506231645"
- lifecycle_state: "RUNNING"
- defined_tags: {
  "ansible_tag_2": {
  "ansibletag448": "test_value"
  }
}
- freeform_tags: {
  "oci:compute:instanceconfiguration": "ocid1.instanceconfiguration.oc1.phx.<unique_ID>",
  "oci:compute:instancepool": "ocid1.instancepool.oc1.phx.<unique_ID>"
}
 
# Enable Cache
cache: yes
cache_plugin: jsonfile
cache_timeout: 7200
cache_connection: /tmp/oci-cache
cache_prefix: oci_

# DB Hosts
fetch_db_hosts: true

For More Information

Detailed information about using the OCI inventory plugin is available on readthedocs.io.

You can also use the following command to see the plugin documentation:

ansible-doc -t inventory oracle.oci.oci

For more information on Ansible, see the official Ansible documentation.