Using Resource Discovery
Discover deployed OCI resources using the Terraform provider.
The OCI Terraform provider's resource discovery feature uses HashiCorp's terraform-exec to import the discovered OCI resources into Terraform configuration and state files.
Prerequisites
Terraform-exec requires the Terraform CLI to be present on your system. See Download and Install Terraform for installation details.
If you are using Terraform version v0.11, this tool cannot generate a state file. Only configurations are supported in v0.11. By default the configurations are generated in v0.12.
If you use v0.13.* of the Terraform CLI, make sure that the version is compatible with v0.12 syntax.
Additionally, you must have the OCI Terraform provider downloaded and installed. See Download and Install the Provider for download instructions.
Adding the Tools to Your Path
To run the OCI Terraform provider as an executable and use resource discovery, you can:
- Add
terraform-provider-oci
to your system path. - Run the provider from the directory where it is located.
- Specify the full path to the provider when you run resource discovery commands.
Because resource discovery commands use terraform-exec to call Terraform on your behalf, your system must specify the location of the Terraform CLI using either of the following methods:
- Provide the full path including name for the Terraform CLI using the
terraform_bin_path
environment variable. See Environment Variables for more information on setting variables. - Add the Terraform CLI to your system path.
Authentication
To discover resources in your compartment, the OCI Terraform provider needs authentication information about the user, tenancy, and region with which to discover the resources. It is recommended that you specify a user that has access to inspect and read the resources to discover.
You can use API Key Authentication and Environment Variables or Instance Principal Authorization to provide the required information.
Exporting Resources
After you have specified the location of the Terraform CLI and authentication settings, either of the following commands can be used to export a compartment's resources:
terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path>
These commands discover all supported resources within the compartment and generate Terraform configuration files in the provided output_path
. The generated .tf
files contain the Terraform configuration with the resources that the command has discovered.
Ensure that the
output_path
is empty before running resource discovery.The following common parameter combinations export the resources described:
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_seperated_list>
- Tenancy and compartment scope resources for the services specified.compartment_id=<non-root_OCID> services=<empty_or_not_specified>
- All compartment scope resources.compartment_id=<non-root_OCID> services=<comma_seperated_list>
- Compartment scope resources for the services specified. Tenancy scope resources aren't discovered even if services with such resources are specified.
Export of compartment resources supports only the target compartment. Resources in child compartments aren't discovered.
Parameters
You can use the following parameters to control the behavior of the resource discovery tool.
Parameter | Details |
---|---|
command |
The command to run. Supported commands include:
|
compartment_id |
The OCID of the compartment to export. If compartment_id or compartment_name isn't specified, the root compartment is used. Required if using Instance Principal Authorization. |
compartmet_name |
The name of a compartment to export. If compartment_id or compartment_name isn't specified, the root compartment is used. |
exclude_services |
A comma-separated list of service resources to exclude from the export. Any service present in both services and exclude_services argument is excluded. |
filter |
Filter discovered resources by specified criteria. For more information, see Filtering Resources. |
generate_state |
Provide this flag to import the discovered resources into a state file in addition to the Terraform configuration files. |
ids |
A comma-separated list of tuples <resource_type:resource_ID> (for example, oci_core_instance:ocid..... ) for resources to export. The ID could either be an OCID or a Terraform import ID. By default, all resources are exported. |
list_export_services_path |
The full path, including the filename, to use as the output for list of supported services, in JSON format. |
output_path |
The absolute path to output the generated configurations and state files of the exported compartment. |
parallelism |
The number of threads to discover resources in parallel. The default value is 1 . |
retry_timeout |
The time duration in seconds for which API calls wait and retry the operation in case of API errors. By default, the retry timeout duration is 15 seconds. |
services |
A comma-separated list of service resources to export. If not specified, all resources within the provided compartment (excluding IAM resources) are exported. See Supported Services for accepted values and Exporting Identity Resources for related information. |
tf_version |
The version of Terraform syntax to use when generating configuration files. The default is v0.12. The allowed values are:
If you specify If you use Terraform CLI v0.13 and greater to discover resources, ensure that the version is compatible with v0.12 syntax. State files are generated in Terraform syntax matching the version of the Terraform CLI used to discover resources. Thetf_version parameter doesn't apply to state files. |
variables_global_level |
List top-level attributes to export as variables, following the format |
variables_resource_level |
List resource-level attributes to export as variables, following the format |
Filtering Resources
Filter discovered resources by specified criteria:
-
Resource type filter:
Type<operator><provider-resource-type>
<operator> is either
=
(equal to) or!=
(not equal to) - Attribute filter:
AttrName=<attribute-name>;Value<operator><value>
Find all resources with matching attribute and value - Up to 10 filters (resources must satisfy all)
- Resource type filter: VCN only
-
--filter="Type=oci_core_vcn"
- Resource type filter: Anything but VCN
-
--filter="Type!=oci_core_vcn"
- Attribute filter: Defined tag value
-
--filter="AttrName=defined_tags.example-namespace.example-key;Value=example-value"
- Multiple filters: VCN only, must have dns_label attribute set to test
-
--filter="Type=oci_core_vcn" --filter="AttrName=dns_label;Value=test"
For more information about filtering discovered resources, see Filtering Resources discovered via Resource Discovery.
Verbose Logging
To get verbose console output when the provider is running, precede the resource discovery command with the TF_LOG
or OCI_TF_LOG
flags. For example:
TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
OCI_TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
The TF_LOG
level and OCI_TF_LOG
flags can also be set as environment variables.
To redirect verbose console output to a log file, set the OCI_TF_LOG_PATH
environment variable and provide the path.
Exit Status
For any error related to the OCI APIs or service unavailability while discovering resources, the tool moves on to find next resource. All errors encountered are displayed after the discovery is complete.
- Exit code
0
- Success. - Exit code
1
- Failure because of errors such as incorrect environment variables, arguments, or configuration. - Exit code
64
- Partial success. Resource discovery was not able to find all the resources because of service failures.
Exporting Identity Resources
terraform-provider-oci -command=export -output_path=<output_path> -services=identity
When exporting identity resources, the
compartment_id
value, if provided, is ignored.Exporting Resources to Another Compartment
Once you have reviewed the generated Terraform configuration files and made any necessary changes, 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=<target_tenancy_OCID>
export TF_VAR_compartment_ocid=<target_compartment_OCID>
Then run the following command:
terraform apply
Generating a Terraform State File
The state file contains all resource attributes that are specified as part of configuration files. If you manage any sensitive data with Terraform, such as database or user passwords or instance private keys, treat the state file itself as sensitive data. See Storing Sensitive Data for more information.
It is also possible to generate a Terraform state file to manage the discovered resources. To do so, run the following command, which includes the -generate_state
flag:
terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path> -generate_state
The results of this command are both the .tf
files representing the Terraform configuration and a terraform.tfstate
file representing the state. See State for more information.
The Terraform state file generated by this command is only compatible with Terraform v0.12.4 and greater.