Using Resource Discovery
The Oracle Cloud Infrastructure (OCI) Terraform provider's resource discovery feature uses HashiCorp's terraform-exec to import the discovered OCI resources into Terraform configuration and state files.
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:
terraform-provider-ocito 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_pathenvironment variable. See Environment Variables for more information on setting variables.
- Add the Terraform CLI to your system path.
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.
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_pathis empty before running resource discovery.
compartment_idparameter is required if using Instance Principal Authorization.
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.
You can use the following parameters to control the behavior of the resource discovery tool.
||The command to run. Supported commands include:
||The OCID of the compartment to export. If
||The name of a compartment to export. If
||A comma-separated list of service resources to exclude from the export. Any service present in both
||Filter discovered resources by specified criteria. For more information, see Filtering Resources.|
||Provide this flag to import the discovered resources into a state file in addition to the Terraform configuration files.|
||A comma-separated list of tuples
||The full path, including the filename, to use as the output for list of supported services, in JSON format.|
||The absolute path to output the generated configurations and state files of the exported compartment.|
||The number of threads to discover resources in parallel. The default value is
||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.|
||A comma-separated list of service resources to export. If not specified, all resources within the provided compartment (excluding IAM resources) are exported.|
||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. The
List top-level attributes to export as variables, following the format
List resource-level attributes to export as variables, following the format
Filter discovered resources by specified criteria:
Resource type filter:
<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
- Resource type filter: Anything but VCN
- Attribute filter: Defined tag value
- Multiple filters: VCN only, must have dns_label attribute set to test
For more information about filtering discovered resources, see Filtering Resources discovered via Resource Discovery.
To get verbose console output when the provider is running, precede the resource discovery command with the
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>
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.
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
- 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_idvalue, 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:
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, like database or user passwords or instance private keys, you should 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
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 above.