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.
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/
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.
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
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
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
command
- Command to run. Supported commands include:
export
- Discovers Oracle Cloud Infrastructure resources within your compartment and generates Terraform configuration files for themlist_export_resources
- Lists the Terraform Oracle Cloud Infrastructure resources types that can be discovered by the export
commandlist_export_services
- Lists the allowed values for services arguments along with scope in json formatcompartment_id
- OCID of a compartment to export. If compartment_id
or compartment_name
is not specified, the root compartment will be usedcompartment_name
- The name of a compartment to export. Use this instead of compartment_id
to provide a compartment nameexclude_services
- Comma-separated list of service resources to exclude from export. If a service is present in both 'services' and 'exclude_services' argument, it will be excludedgenerate_state
- Provide this flag to import the discovered resources into a state file along with the Terraform configurationids
- Comma-separated list of tuples resource ID
or resource Type:resource ID
e.g. ocid.....
or oci_core_instance:ocid.....
for resources to export. The ID could either be an OCID or a Terraform import ID. If resource ID
format is used then sub-resources are also discovered and if resource Type:resource ID
format is used, only resource id's given are discovered. By default, all resources are exported if ids is not added.output_path
- Absolute path to output generated configurations and state files of the exported compartmentparallelism
- The number of threads to use for resource discovery. By default the value is 1variables_resource_level
- List of resource-level attributes to export as variables, following the format resourceType.attribute
. Top-level attributes (see variables_global_level
) are excluded from this list.variables_global_level
- List of top-level attributes to export as variables, following the format attribute1,attribute2
. Resource-level attributes (see variables_resource_level
) are excluded from this list.retry_timeout
- The time duration for which API calls will wait and retry operation in case of API errors. By default, the retry timeout duration is 15sservices
- 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:
adm
- Discovers adm resources within the specified compartmentai_anomaly_detection
- Discovers ai_anomaly_detection resources within the specified compartmentai_document
- Discovers ai_document resources within the specified compartmentai_language
- Discovers ai_language resources within the specified compartmentai_vision
- Discovers ai_vision resources within the specified compartmentanalytics
- Discovers analytics resources within the specified compartmentannouncements_service
- Discovers announcements_service resources within the specified compartmentapigateway
- Discovers apigateway resources within the specified compartmentapm
- Discovers apm resources within the specified compartmentapm_config
- Discovers apm_config resources within the specified compartmentapm_synthetics
- Discovers apm_synthetics resources within the specified compartmentartifacts
- Discovers artifacts resources within the specified compartmentauto_scaling
- Discovers auto_scaling resources within the specified compartmentbastion
- Discovers bastion resources within the specified compartmentbds
- Discovers big data service resources within the specified compartmentblockchain
- Discovers blockchain resources within the specified compartmentbudget
- Discovers budget resources across the entire tenancycapacity_management
- Discovers capacity_management resources within the specified compartmentcertificates_management
- Discovers certificates_management resources within the specified compartmentcloud_bridge
- Discovers cloud_bridge resources within the specified compartmentcloud_guard
- Discovers cloud guard resources within the specified compartmentcloud_migrations
- Discovers cloud_migrations resources within the specified compartmentcluster_placement_groups
- Discovers cluster_placement_groups resources within the specified compartmentcompute_cloud_at_customer
- Discovers compute_cloud_at_customer resources within the specified compartmentcontainer_instances
- Discovers container_instances resources within the specified compartmentcontainerengine
- Discovers containerengine resources within the specified compartmentcore
- Discovers compute, block storage, and networking resources within the specified compartmentdata_labeling_service
- Discovers data_labeling_service resources within the specified compartmentdata_safe
- Discovers data_safe resources within the specified compartmentdatabase
- Discovers database resources within the specified compartmentdatabase_migration
- Discovers database_migration resources within the specified compartmentdatabase_tools
- Discovers database_tools resources within the specified compartmentdatacatalog
- Discovers datacatalog resources within the specified compartmentdataflow
- Discovers dataflow resources within the specified compartmentdataintegration
- Discovers dataintegration resources within the specified compartmentdatascience
- Discovers datascience resources within the specified compartmentdevops
- Discovers devops resources within the specified compartmentdisaster_recovery
- Discovers disaster_recovery resources within the specified compartmentdns
- Discovers dns resources (except record) within the specified compartmentem_warehouse
- Discovers em_warehouse resources within the specified compartmentemail
- Discovers email_sender resources within the specified compartmentevents
- Discovers events resources within the specified compartmentfile_storage
- Discovers file_storage resources within the specified compartmentfunctions
- Discovers functions resources within the specified compartmentfusion_apps
- Discovers fusion_apps resources within the specified compartmentgenerative_ai
- Discovers generative_ai resources within the specified compartmentgolden_gate
- Discovers golden_gate resources within the specified compartmenthealth_checks
- Discovers health_checks resources within the specified compartmentidentity
- Discovers identity resources across the entire tenancyidentity_data_plane
- Discovers identity_data_plane resources within the specified compartmentidentity_domains
- Discovers identity_domains resources within the specified compartmentintegration
- Discovers integration resources within the specified compartmentjms
- Discovers jms resources within the specified compartmentkms
- Discovers kms resources within the specified compartmentlicense_manager
- Discovers license_manager resources within the specified compartmentlimits
- Discovers limits resources across the entire tenancyload_balancer
- Discovers load balancer resources within the specified compartmentlog_analytics
- Discovers log_analytics resources within the specified compartmentlogging
- Discovers logging resources within the specified compartmentmanagement_agent
- Discovers management_agent resources within the specified compartmentmarketplace
- Discovers marketplace resources within the specified compartmentmedia_services
- Discovers media_services resources within the specified compartmentmetering_computation
- Discovers metering_computation resources across the entire tenancymonitoring
- Discovers monitoring resources within the specified compartmentmysql
- Discovers mysql resources within the specified compartmentnetwork_firewall
- Discovers network_firewall resources within the specified compartmentnetwork_load_balancer
- Discovers network load balancer resources within the specified compartmentnosql
- Discovers nosql resources within the specified compartmentobject_storage
- Discovers object storage resources within the specified compartmentoce
- Discovers oce resources within the specified compartmentocvp
- Discovers ocvp resources within the specified compartmentoda
- Discovers oda resources within the specified compartmentons
- Discovers ons resources within the specified compartmentopa
- Discovers opa resources within the specified compartmentopensearch
- Discovers opensearch resources within the specified compartmentoperator_access_control
- Discovers operator_access_control resources within the specified compartmentopsi
- Discovers opsi resources within the specified compartmentoptimizer
- Discovers optimizer resources across the entire tenancyos_management_hub
- Discovers os_management_hub resources within the specified compartmentosmanagement
- Discovers osmanagement resources within the specified compartmentosp_gateway
- Discovers osp_gateway resources within the specified compartmentpsql
- Discovers psql resources within the specified compartmentqueue
- Discovers queue resources within the specified compartmentrecovery
- Discovers recovery resources within the specified compartmentredis
- Discovers redis resources within the specified compartmentresourcemanager
- Discovers resourcemanager resources within the specified compartmentsch
- Discovers sch resources within the specified compartmentservice_mesh
- Discovers service_mesh resources within the specified compartmentstack_monitoring
- Discovers stack_monitoring resources within the specified compartmentstreaming
- Discovers streaming resources within the specified compartmentusage_proxy
- Discovers usage_proxy resources within the specified compartmentvault
- Discovers vault resources within the specified compartmentvbs_inst
- Discovers vbs_inst resources across the entire tenancyvisual_builder
- Discovers visual_builder resources within the specified compartmentvn_monitoring
- Discovers vn_monitoring resources within the specified compartmentvulnerability_scanning
- Discovers vulnerability_scanning resources within the specified compartmentwaa
- Discovers waa resources within the specified compartmentwaas
- Discovers waas resources within the specified compartmentwaf
- Discovers waf resources within the specified compartmenttf_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:
Arguments | Resources discovered |
---|---|
compartment_id = \ services= \ | all tenancy and compartment scope resources |
compartment_id = \ services= \ |
tenancy and compartment scope resources for the services specified |
compartment_id = \ services= \ | all compartment scope resources only |
compartment_id = \ 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
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.
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:
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 acompartment_id
is specified, the value will be ignored for discovering identity resources.
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
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
You can filter resources discovered by resource discovery by specifying filtering criteria.
Operator
=
Equal to!=
Not Equal toFilter Types
Type<Operator><Provider Resource Type>
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
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
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
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