Resource Discovery

Overview

Terraform Resource Discovery can be used to discover deployed resources within a compartment and export them to Terraform configuration and state files. Refer to the Supported Resources for details.

Use Cases and Benefits

With this feature, you can perform the following tasks:

Please note that this feature is available for version 3.50 and above. The latest version of the terraform-oci-provider can be downloaded using terraform init or by going to https://releases.hashicorp.com/terraform-provider-oci/

Note: Resource discovery is not a migration tool. For cloning or migrating resources, configurations generated by Resource Discovery are a starting point and may require some changes.

Prerequisites

Download the latest terraform-oci-provider from provider releases. After downloading, in order to run the executable:

* either add the terraform-provider-oci executable to PATH
* or run the executable giving the full path or from the directory where it is located

Resource discovery uses Hashicorp’s terraform-exec to import the discovered resources into the state file. Terraform exec requires terraform CLI to be present on your system. Download the appropriate package for your system.

Note: Terraform version v0.11.* is not supported by the tool for generating the state file. Only configurations are supported in v0.11. By default the configurations are generated in v0.12. If specifying v0.13.* for the Terraform CLI, make sure that the version is compatible with v0.12 syntax.

The terraform CLI can be provided in 2 ways:

* provide full path including name for the terraform CLI using environment variable `terraform_bin_path`
  OR
* add terraform CLI to the system path and the tool will find it

Authentication

To discover resources in your compartment, the terraform-oci-provider will need authentication information about the user, tenancy, and region with which to discover the resources. It is recommended to specify a user that has access to inspect and read the resources to discover.

Resource discovery supports API Key based authentication and Instance Principal based authentication.

The authentication information can be specified using the following environment variables:

export TF_VAR_tenancy_ocid=<value>
export TF_VAR_user_ocid=<value>
export TF_VAR_fingerprint=<value>
export TF_VAR_private_key_path=<path to your private key>
export TF_VAR_region=<region of the resources, e.g. "us-phoenix-1">

If your private key is password-encrypted, you may also need to specify a password with this variable:

export TF_VAR_private_key_password=<password for private key>

The authentication information can also be specified using a configuration file. For details on setting this up, see SDK and CLI configuration file A non-default profile can be set using environment variable:

export TF_VAR_config_file_profile=<value>

If the parameters have multiple sources, the priority will be in the following order:

Environment variables
Non-default profile
DEFAULT profile

Usage

Once you have specified the prerequisite authentication settings, the command can be used as follows with a compartment being specified by name or OCID:

terraform-provider-oci -command=export -compartment_name=<name of compartment to export> -output_path=<absolute path to directory under which to generate Terraform files>

terraform-provider-oci -command=export -compartment_id=<OCID of compartment to export> -output_path=<absolute path to directory under which to generate Terraform files>

This command will discover resources within your compartment and generates Terraform configuration files in the given output_path. The generated .tf files contain the Terraform configuration with the resources that the command has discovered.

Note: Make sure the output_path is empty before running resource discovery

Parameter Description

Arguments Resources discovered
compartment_id = <empty or tenancy ocid>
services= <empty> or not specified		 all tenancy and compartment scope resources
compartment_id = <empty or tenancy ocid>
services= <comma separated list of services>		 tenancy and compartment scope resources for the services specified
compartment_id = <non-root compartment>
services= <empty> or not specified		 all compartment scope resources only
compartment_id = <non-root compartment>
services=<comma separated list of services>		 compartment scope resources for the services specified
tenancy scope resources will not be discovered even if services with such resources are specified

Notes: * The compartment export functionality currently supports discovery of the target compartment. The ability to discover resources in child compartments is not yet supported. * If using Instance Principals, resources can not be discovered if compartment_id is not specified

Exit status

While discovering resources if there is any error related to the APIs or service unavailability, the tool will move on to find next resource. All the errors encountered will be displayed after the discovery is complete.

Generated Terraform Configuration Contents

The command will discover resources that are in an active or usable state. Resources that have been terminated or otherwise made inactive are generally excluded from the generated configuration.

By default, the Terraform names of the discovered resources will share the same name as the display name for that resource, if one exists.

The attributes of the resources will be populated with the values that are returned by the Oracle Cloud Infrastructure services.

In some cases, a required or optional attribute may not be discoverable from the Oracle Cloud Infrastructure services and may be omitted from the generated Terraform configuration. This may be expected behavior from the service, which may prevent discovery of certain sensitive attributes or secrets. In such cases, placeholder value will be set along with a comment like this:

admin_password = "<placeholder for missing required attribute>" #Required attribute not found in discovery, placeholder value set to avoid plan failure

The missing required attributes will also be added to lifecycle ignore_changes. This is done to avoid terraform plan failure when moving manually-managed infrastructure to Terraform-managed infrastructure. Any changes made to such fields will not reflect in terraform plan. If you want to update these fields, remove them from ignore_changes.

Resources that are dependent on availability domains will be generated under availability_domain.tf file. These include: * oci_core_boot_volume * oci_file_storage_file_system * oci_file_storage_mount_target * oci_file_storage_snapshot

Exporting Identity Resources

Some resources, such as identity resources, may exist only at the tenancy level and cannot be discovered within a specific compartment. To discover such resources, specify the following command.

terraform-provider-oci -command=export -output_path=<absolute path to directory under which to generate Terraform files> -services=identity

Note: When exporting identity resources, a compartment_id is not required. If a compartment_id is specified, the value will be ignored for discovering identity resources.

Exporting Resources to Another Compartment

Once the user has reviewed the generated configuration and made the necessary changes to reflect the desired settings, the configuration can be used with Terraform. One such use case is the re-deploying of those resources in a new compartment or tenancy, using Terraform.

To do so, specify the following environment variables:

export TF_VAR_tenancy_ocid=<new tenancy OCID>
export TF_VAR_compartment_ocid=<new compartment OCID>

And run

terraform apply

Generating a Terraform State File

Using this command it is also possible to generate a Terraform state file to manage the discovered resources. To do so, run the following command:

terraform-provider-oci -command=export -compartment_id=<compartment to export> -output_path=<absolute path to directory under which to generate Terraform files> -generate_state

The results of this command are both the .tf files representing the Terraform configuration and a terraform.tfstate file representing the state.

Note The Terraform state file generated by this command is currently compatible with Terraform v0.12.4 and above

Filtering Resources discovered via Resource Discovery

You can filter resources discovered by resource discovery by specifying filtering criteria. * You can filter resources by terraform resource type or by attribute key values * You can pass multiple filters so that resources satisfying all of these filters will be discovered * You can pass a maximum of 10 filters

Operator * = Equal to * != Not Equal to

Filter Types * Resource Type filter : Type<Operator><Provider Resource Type> * Attribute Filter : AttrName=<attribute name>;Value<Operator><value> Find all resources with matching attribute and value

--filter="Type=oci_core_vcn"                                                            // discover resources of type oci_core_vcn
--filter="Type!=oci_core_vcn"                                                           // discover resources except resources of type oci_core_vcn
--filter="AttrName=defined_tags.example-namespace.example-key;Value=example-value"      // discover resources of with defined tag example-namespace.example-key and value as example-value

Example for specifying multiple filters

--filter="Type=oci_core_vcn" --filter="AttrName=dns_label;Value=test"     // discover resources of type oci_core_vcn such that they have dns_label attribute value as test

Discover all resources

If TF_DISCOVER_ALL_STATES is set to 1, then Resource Discovery will try to discover all resources irrespective of their lifecycle state.

export TF_DISCOVER_ALL_STATES=1

Supported Resources

As of this writing, the list of Terraform services and resources that can be discovered by the command is as follows. The list of supported resources can also be retrieved by running this command:

terraform-provider-oci -command=list_export_resources

adm

ai_anomaly_detection

ai_document

ai_language

ai_vision

analytics

announcements_service

apigateway

apm

apm_config

apm_synthetics

artifacts

auto_scaling

bastion

bds

blockchain

budget

capacity_management

certificates_management

cloud_bridge

cloud_guard

cloud_migrations

cluster_placement_groups

compute_cloud_at_customer

container_instances

containerengine

core

data_labeling_service

data_safe

database

database_migration

database_tools

datacatalog

dataflow

dataintegration

datascience

devops

disaster_recovery

dns

em_warehouse

email

events

file_storage

functions

fusion_apps

generative_ai

golden_gate

health_checks

identity

identity_data_plane

identity_domains

integration

jms

kms

license_manager

limits

load_balancer

log_analytics

logging

management_agent

marketplace

media_services

metering_computation

monitoring

mysql

network_firewall

network_load_balancer

nosql

object_storage

oce

ocvp

oda

ons

opa

opensearch

operator_access_control

opsi

optimizer

os_management_hub

osmanagement

osp_gateway

psql

queue

recovery

redis

resourcemanager

sch

service_mesh

stack_monitoring

streaming

usage_proxy

vault

vbs_inst

visual_builder

vn_monitoring

vulnerability_scanning

waa

waas

waf