oracle.oci.oci – Oracle Cloud Infrastructure (OCI) inventory plugin

Note

This plugin is part of the oracle.oci collection (version 5.5.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install oracle.oci.

To use it in a playbook, specify: oracle.oci.oci.

Synopsis

  • Get inventory hosts from oci.

  • Uses a <name>.oci.yaml (or <name>.oci.yml) YAML configuration file.

Parameters

Parameter Choices/Defaults Configuration Comments
api_user_key_file
string
env:OCI_USER_KEY_FILE
Full path and filename of the private key (in PEM format). If the key is encrypted with a pass-phrase, the pass_phrase option must also be provided. Preference order is .oci.yml > OCI_USER_KEY_FILE environment variable > settings from config file This option is required if the private key is not specified through a configuration file (See config_file)
api_user_key_pass_phrase
string
env:OCI_USER_KEY_PASS_PHRASE
Passphrase used by the key referenced in api_user_key_file, if it is encrypted. Preference order is .oci.yml > OCI_USER_KEY_PASS_PHRASE environment variable > settings from config file This option is required if the passphrase is not specified through a configuration file (See config_file)
auth_type
string
    Choices:
  • api_key ←
  • instance_principal
  • instance_obo_user
  • resource_principal
  • security_token
env:OCI_ANSIBLE_AUTH_TYPE
The type of authentication to use for making API requests. By default auth_type="api_key" based authentication is performed and the API key (see api_user_key_file) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, if any, is used. Use auth_type="instance_principal" to use instance principal based authentication when running ansible playbooks within an OCI compute instance.
cache
boolean
    Choices:
  • no ←
  • yes
ini entries:

[inventory]
cache = no

env:ANSIBLE_INVENTORY_CACHE
Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.
cache_connection
string
ini entries:

[defaults]
fact_caching_connection = None

[inventory]
cache_connection = None

env:ANSIBLE_CACHE_PLUGIN_CONNECTION
env:ANSIBLE_INVENTORY_CACHE_CONNECTION
Cache connection data or path, read cache plugin documentation for specifics.
cache_plugin
string
Default:
"memory"
ini entries:

[defaults]
fact_caching = memory

[inventory]
cache_plugin = memory

env:ANSIBLE_CACHE_PLUGIN
env:ANSIBLE_INVENTORY_CACHE_PLUGIN
Cache plugin to use for the inventory's source data.
cache_prefix
string
Default:
"ansible_inventory_"
ini entries:

[default]
fact_caching_prefix = ansible_inventory_

Removed in: version 2.16 of ansible.builtin
Why: Fixes typing error in INI section name
Alternative: Use the 'defaults' section instead

[defaults]
fact_caching_prefix = ansible_inventory_

[inventory]
cache_prefix = ansible_inventory_

env:ANSIBLE_CACHE_PLUGIN_PREFIX
env:ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX
Prefix to use for cache plugin files/tables
cache_timeout
integer
Default:
3600
ini entries:

[defaults]
fact_caching_timeout = 3600

[inventory]
cache_timeout = 3600

env:ANSIBLE_CACHE_PLUGIN_TIMEOUT
env:ANSIBLE_INVENTORY_CACHE_TIMEOUT
Cache duration in seconds
compartments
list / elements=string
A dictionary of compartment identifier to obtain list of hosts. This config parameter is optional. If compartment is not specified, the plugin fetches all compartments from the tenancy.
compartment_name
string
Name of the compartment. If None and `compartment_ocid` is not set, all the compartments including the root compartment are returned.
compartment_ocid
string
OCID of the compartment. If None, root compartment is assumed to be the default value.
fetch_hosts_from_subcompartments
boolean
    Choices:
  • no
  • yes
Flag used to fetch hosts from subcompartments. Default value is set to True
parent_compartment_ocid
string
This option is not needed when the compartment_ocid option is used, it is needed when compartment_name is used. OCID of the parent compartment. If None, root compartment is assumed to be parent.
compose
dictionary
Default:
{}
Create vars from jinja2 expressions.
config_file
string
Default:
"~/.oci/config"
env:OCI_CONFIG_FILE
The oci config path. Either pass the '/full/path/to/config/file' in inventory plugin configuration file. Or pass the 'relative/path/to/config/file' with respect to the directory from where inventory command is executed. Relative path should not be relative with respect to inventory plugin configuration file.
config_profile
string
Default:
"DEFAULT"
env:OCI_CONFIG_PROFILE
The config profile to use.
debug
boolean
    Choices:
  • no
  • yes
Parameter to enable logs while running the inventory plugin. Default value is set to False
default_groups
list / elements=string
OCI Inventory plugin creates some groups by default based on these properties ["availability_domain", "compartment_name", "region", "freeform_tags", "defined_tags"]. If you don't want OCI inventory plugin to create these default groups, you can use this option to configure which of these default groups should be created. This option takes a list of properties of inventory hosts based on which the groups will be created. The supported properties are - "availability_domain" - "compartment_name" - "region" - "freeform_tags" - "defined_tags" if empty list is passed to this option, none of the default groups are created. default_groups and default_groups_preferences cannot be used together We recommend to use default_groups_preferences parameter as we will deprecate default_groups parameter in our next major upgrade
default_groups_preferences
dictionary
OCI Inventory plugin creates some groups by default based on these properties ["availability_domain", "compartment_name", "region", "freeform_tags", "defined_tags"]. If you don't want OCI inventory plugin to create these default groups, you can use this option to configure which of these default groups should be created. This option takes a dict of properties of inventory hosts based on which the groups will be created. You can also pass a list of jinja2 expressions under include and exclude if you want to include specific groups to be included/excluded based on these criteria if empty list is passed to this option, none of the default groups are created. default_groups and default_groups_preferences cannot be used together
availability_domain
dictionary
Add groups based on the availability_domain
exclude
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, none of the availability_domain will be excluded. if any group is present in both include and exclude, then that group will be excluded.
include
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, all availability_domain will be included which are not in exclude list
compartment_name
dictionary
Add groups based on the compartment_name
exclude
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, none of the compartment_name will be excluded. if any group is present in both include and exclude, then that group will be excluded.
include
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, all compartment_name will be included which are not in exclude list
defined_tags
dictionary
Add groups based on the defined_tags
exclude
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, none of the defined_tags will be excluded. if any group is present in both include and exclude, then that group will be excluded.
include
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, all defined_tags will be included which are not in exclude list
freeform_tags
dictionary
Add groups based on the freeform_tags
exclude
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, none of the freeform_tags will be excluded. if any group is present in both include and exclude, then that group will be excluded.
include
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, all freeform_tags will be included which are not in exclude list
region
dictionary
Add groups based on the region
exclude
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, none of the regions will be excluded. if any group is present in both include and exclude, then that group will be excluded.
include
list / elements=string
A list of jinja2 expressions. if this option is not used or empty, all regions will be included which are not in exclude list
delegation_token_file
string
env:OCI_DELEGATION_TOKEN_FILE
Path to delegation_token file. If not set then the value of the OCI_DELEGATION_TOKEN_FILE environment variable, if any, is used. Otherwise, defaults to config_file.
This parameter is only applicable when auth_type=instance_obo_user is set.
enable_ipv6
boolean
    Choices:
  • no
  • yes ←
Fetch IPv6 address information from VNICs. Default value set to True.
enable_parallel_processing
string
Default:
"yes"
Use multiple threads to speedup lookup. Default is set to True
exclude_compartments
list / elements=string
A dictionary of compartment identifier to filter the compartments from which hosts should be listed from. This config parameter is optional. Suboption is not considered when both compartment_ocid, compartment_name are None
compartment_name
string
Name of the compartment. If None and `compartment_ocid` is not set, this option is not considered for filtering the compartments. If both compartment_ocid and compartment_name are passed, compartment_ocid is considered
compartment_ocid
string
OCID of the compartment.
parent_compartment_ocid
string
This option is not needed when the compartment_ocid option is used, it is needed when compartment_name is used. OCID of the parent compartment. If None, root compartment is assumed to be parent.
skip_subcompartments
boolean
    Choices:
  • no
  • yes
Flag used to skip the sub-compartments. Default value is set to True
exclude_host_filters
list / elements=string
A list of Jinja2 conditional expressions. Each expression in the list is evaluated for each host; when any of the expressions is evaluated to Truthy value, the host is excluded from the inventory. exclude_host_filters take priority over the include_host_filters and filters.
fetch_compute_hosts
boolean
    Choices:
  • no
  • yes
When set, the compute nodes are fetched. Default value set to True.
fetch_db_hosts
boolean
    Choices:
  • no
  • yes
When set, the db nodes are also fetched. Default value set to False.
filters
list / elements=string
A dictionary of filter value pairs.
Available filters are display_name, lifecycle_state, availability_domain, defined_tags, freeform_tags.
Note: defined_tags and freeform_tags filters are not supported for db hosts. The db hosts will not be returned when you use either of these filters.
groups
dictionary
Default:
{}
Add hosts to group based on Jinja2 conditionals.
hostname_format
string
env:OCI_HOSTNAME_FORMAT
Host naming format to use. Use 'fqdn' to list hosts using the instance's Fully Qualified Domain Name (FQDN). These FQDNs are resolvable within the VCN using the VCN resolver specified through the subnet's DHCP options. Please see https://docs.us-phoenix-1.oraclecloud.com/Content/Network/Concepts/dns.htm for more details. Use 'public_ip' to list hosts using public IP address. Use 'private_ip' to list hosts using private IP address. Use 'display_name' to list hosts using display_name of the Instances. 'display_name' cannot be used when fetch_db_hosts is True. By default, hosts are listed using public IP address. hostname_format_preferences and hostname_format cannot be used together
hostname_format_preferences
list / elements=string
A list of Jinja2 expressions in order of precedence to compose inventory_hostname. Ignores expression if result is an empty string or None value. hostname_format_preferences and hostname_format cannot be used together. The instance is ignored if none of the hostname_format_preferences resulted in a non-empty value
hostnames
list / elements=string
A list of hostnames to search for.
include_host_filters
list / elements=string
A list of Jinja2 conditional expressions. Each expression in the list is evaluated for each host; when any of the expressions is evaluated to Truthy value, the host is included in the inventory. include_host_filters and filters options cannot be used together.
instance_principal_authentication
string
This parameter is DEPRECATED. Please use auth_type instead.
Use instance principal based authentication. If not set, the API key in your config will be used.
keyed_groups
list / elements=dictionary
Default:
[]
Add hosts to group based on the values of a variable.
default_value
string
added in 2.12 of ansible.builtin
The default value when the host variable's value is an empty string.
This option is mutually exclusive with trailing_separator.
key
string
The key from input dictionary used to generate groups
parent_group
string
parent group for keyed group
prefix
string
Default:
""
A keyed group name will start with this prefix
separator
string
Default:
"_"
separator used to build the keyed group name
trailing_separator
boolean
added in 2.12 of ansible.builtin
    Choices:
  • no
  • yes ←
Set this option to False to omit the separator after the host variable when the value is an empty string.
This option is mutually exclusive with default_value.
leading_separator
boolean
added in 2.11 of ansible.builtin
    Choices:
  • no
  • yes ←
Use in conjunction with keyed_groups.
By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
This is because the default prefix is "" and the default separator is "_".
Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
If the group name is derived from a mapping the separator is still used to concatenate the items.
To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
plugin
string / required
    Choices:
  • oracle.oci.oci
token that ensures this is a source file for the 'oci' plugin.
primary_vnic_only
boolean
    Choices:
  • no
  • yes
env:OCI_PRIMARY_VNIC_ONLY
The default behavior of the plugin is to process all VNIC's attached to a compute instance. This might result in instance having multiple entries. When this parameter is set to True, the plugin will only process the primary VNIC and thus having only a single entry for each compute instance.
regions
list / elements=string
A list of regions to search. If not specified, the region is read from config file. Use 'all' to generate inventory from all subscribed regions.
strict
boolean
    Choices:
  • no ←
  • yes
If yes make invalid entries a fatal error, otherwise skip and continue.
Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
use_extra_vars
boolean
added in 2.11 of ansible.builtin
    Choices:
  • no ←
  • yes
ini entries:

[inventory_plugins]
use_extra_vars = no

env:ANSIBLE_INVENTORY_USE_EXTRA_VARS
Merge extra vars into the available variables for composition (highest precedence).

Examples

# Please check https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/ansibleinventoryintro.htm
# for more scenario based examples.

# Fetch all hosts
plugin: oci

# Optional fields:
config_file: ~/.oci/config
config_profile: DEFAULT

# 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..xxxxxx
    fetch_hosts_from_subcompartments: false

  - compartment_name: "test_compartment"
    parent_compartment_ocid: ocid1.tenancy.oc1..xxxxxx

# Sets the inventory_hostname to either "display_name+'.oci.com'" or id or hostname_label
# "'display_name+'.oci.com'" has more preference than id
hostname_format_preferences:
  - "display_name+'.oci.com'"
  - "id"
  - "hostname_label"

# Excludes host that is not in the region 'iad' from the inventory
exclude_host_filters:
  - "region not in ['iad']"

# Includes only the hosts that has display_name ending with '.oci.com' in the inventory
include_host_filters:
  - "display_name is match('.*.oci.com')"

# Example group results by key
keyed_groups:
  - key: availability_domain

# Example to create and modify a host variable
compose:
  ansible_host: display_name+'.oracle.com'

# Example to use_extra_vars and pass the value of extra_vars variable with inventory command
# This requires ansible v2.11 or higher
use_extra_vars: true
compose:
  example: " 'Hello' +  extra_vars"
# pass the value of extra_vars variable with ansible-inventory command using -e option
# ansible-inventory -i /path/to/demo.oci.yml --list -e "extra_vars=ANSIBLE"

# Environment variable can also be used to pass the value of extra_vars variable.
# export TEMP_ENV="ANSIBLE"
# ansible-inventory -i /path/to/demo.oci.yml --list -e "extra_vars='$TEMP_ENV'"

# Example flag to turn on debug mode
debug: true

# Enable Cache
cache: yes
cache_plugin: jsonfile
cache_timeout: 7200
cache_connection: /tmp/oci-cache
cache_prefix: oci_

# DB Hosts
fetch_db_hosts: True

# Compute Hosts (bool type)
fetch_compute_hosts: True

# Process only the primary vnic of a compute instance
primary_vnic_only: True

# Fetch IPv6 address information from VNICs.
enable_ipv6: True

# Select compartment by ocid or name
exclude_compartments:
  - compartment_ocid: ocid1.compartment.oc1..xxxxxx
    skip_subcompartments: false

  - compartment_name: "test_skip_compartment"
    parent_compartment_ocid: ocid1.tenancy.oc1..xxxxxx

# Create groups based on properties
default_groups_preferences:
  region:
    include:
        - region=="us-ashburn-1"
  compartment_name:
    exclude:
        - name=="dev_tests"
  availability_domain:
  freeform_tags:
  defined_tags:
    include:
        - <jinja_expression>
        - namespace=="mynamespace" and namespace.key =="mykey"
        - namespace=="mynamespace2" and namespace.key =="mykey2"
    exclude:
        - <jinja_expression>
        - namespace=="mynamespace3" and namespace.key =="mykey3"