» Resource Discovery
You can use Terraform Resource Discovery to discover deployed resources in your compartment and export them to Terraform configuration and state files. This release supports the most commonly used Oracle Cloud Infrastructure services, such as Compute, Block Volumes, Networking, Load Balancing, Database, and Identity and Access Management (IAM). Please look at the section “Supported Resources” for details.
» Use Cases and Benefits
With this feature, you can perform the following tasks:
Move from manually-managed infrastructure to Terraform-managed infrastructure: You can generate a baseline Terraform state file for your existing infrastructure with a single command, and manage this infrastructure by using Terraform.
Detect state drift: By managing the infrastructure using Terraform, you can detect when the state of your resources changes and differs from the desired configuration.
Duplicate or rebuild existing infrastructure: By creating Terraform configuration files, you can re-create your existing infrastructure architecture in a new tenancy or compartment.
Get started with Terraform: If you’re new to Terraform, you can learn about Terraform’s HCL syntax and how to represent Oracle Cloud Infrastructure resources in HCL.
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/
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:
If the parameters have multiple sources, the priority will be in the following order:
Environment variables Non-default profile DEFAULT profile
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=<directory under which to generate Terraform files>
terraform-provider-oci -command=export -compartment_id=<OCID of compartment to export> -output_path=<directory under which to generate Terraform files>
This command will discover resources within your compartment and generates Terraform configuration files in the given
.tf files contain the Terraform configuration with the resources that the command has discovered.
command- Command to run. Supported commands include:
compartment_id- OCID of a compartment to export. If
compartment_nameis not specified, the root compartment will be used.
compartment_name- The name of a compartment to export. Use this instead of
compartment_idto provide a compartment name.
ids- Comma-separated list of resource IDs to export. The ID could either be an OCID or a Terraform import ID. By default, all resources are exported.
output_path- Path to output generated configurations and state files of the exported compartment
services- Comma-separated list of service resources to export. If not specified, all resources within the given compartment (which excludes identity resources) are exported. The following values can be specified:
analytics- Discovers analytics resources within the specified compartment
apigateway- Discovers apigateway resources within the specified compartment
auto_scaling- Discovers auto_scaling resources within the specified compartment
availability_domain- Discovers availability domains used by your compartment-level resources. It is recommended to always specify this value.
bds- Discovers big data service resources within the specified compartment
budget- Discovers budget resources across the entire tenancy
containerengine- Discovers containerengine resources within the specified compartment
core- Discovers compute, block storage, and networking resources within the specified compartment
data_safe- Discovers data_safe resources within the specified compartment
database- Discovers database resources within the specified compartment
datacatalog- Discovers datacatalog resources within the specified compartment
dataflow- Discovers dataflow resources within the specified compartment
datascience- Discovers datascience resources within the specified compartment
dataintegration- Discovers dataintegration resources within the specified compartment
dns- Discovers dns resources (except record) within the specified compartment
events- Discovers events resources within the specified compartment
file_storage- Discovers file_storage resources within the specified compartment
functions- Discovers functions resources within the specified compartment
health_checks- Discovers health_checks resources within the specified compartment
integration- Discovers integration resources within the specified compartment
identity- Discovers identity resources across the entire tenancy
kms- Discovers kms resources within the specified compartment
limits- Discovers limits resources across the entire tenancy
load_balancer- Discovers load balancer resources within the specified compartment
marketplace- Discovers marketplace resources within the specified compartment
monitoring- Discovers monitoring resources within the specified compartment
mysql- Discovers mysql resources within the specified compartment
nosql- Discovers nosql resources within the specified compartment
oce- Discovers oce resources within the specified compartment
ocvp- Discovers ocvp resources within the specified compartment
object_storage- Discovers object storage resources within the specified compartment
oda- Discovers oda resources within the specified compartment
ons- Discovers ons resources within the specified compartment
osmanagement- Discovers osmanagement resources within the specified compartment
streaming- Discovers streaming resources within the specified compartment
tagging- Discovers tag-related resources within the specified compartment
waas- Discovers waas resources within the specified compartment
generate_state- Provide this flag to import the discovered resources into a state file along with the Terraform configuration
tf_version- The version of terraform syntax to generate for configurations. Default is v0.12. The state file will be written in v0.12 only. The allowed values are:
|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.
- Exit code 0 - Success
- Exit code 1 - Failure due to errors such as incorrect environment variables, arguments or configuration
- Exit code 2 - Partial Success when resource discovery was not able to find all the resources because of the service failures
» 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
Resources that are dependent on availability domains will be generated under
availability_domain.tf file. These include:
» 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=<directory under which to generate Terraform files> -services=identity
Note: When exporting identity resources, a
compartment_idis not required. If a
compartment_idis 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>
» 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=<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
» 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: