» Resource Discovery

» Overview

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/

» 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=<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 output_path. The generated .tf files contain the Terraform configuration with the resources that the command has discovered.

Parameter Description

  • command - Command to run. Supported commands include:
    • export - Discovers Oracle Cloud Infrastructure resources within your compartment and generates Terraform configuration files for them
    • list_export_resources - Lists the Terraform Oracle Cloud Infrastructure resources types that can be discovered by the export command
  • compartment_id - OCID of a compartment to export. If compartment_id or compartment_name is not specified, the root compartment will be used.
  • compartment_name - The name of a compartment to export. Use this instead of compartment_id to 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
    • email - Discovers email resources 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:
    • 0.11
    • 0.12
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.

  • 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 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=<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=<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:

terraform-provider-oci -command=list_export_resources

analytics

  • oci_analytics_analytics_instance

apigateway

  • oci_apigateway_gateway
  • oci_apigateway_deployment

auto_scaling

  • oci_autoscaling_auto_scaling_configuration

bds

  • oci_bds_bds_instance

budget

  • oci_budget_budget
  • oci_budget_alert_rule

containerengine

  • oci_containerengine_cluster
  • oci_containerengine_node_pool

core

  • oci_core_boot_volume_backup
  • oci_core_boot_volume
  • oci_core_console_history
  • oci_core_cluster_network
  • oci_core_compute_image_capability_schema
  • oci_core_cpe
  • oci_core_cross_connect_group
  • oci_core_cross_connect
  • oci_core_dhcp_options
  • oci_core_drg_attachment
  • oci_core_drg
  • oci_core_dedicated_vm_host
  • oci_core_image
  • oci_core_instance_configuration
  • oci_core_instance_console_connection
  • oci_core_instance_pool
  • oci_core_instance
  • oci_core_internet_gateway
  • oci_core_ipsec
  • oci_core_local_peering_gateway
  • oci_core_nat_gateway
  • oci_core_network_security_group
  • oci_core_network_security_group_security_rule
  • oci_core_private_ip
  • oci_core_public_ip
  • oci_core_remote_peering_connection
  • oci_core_route_table
  • oci_core_security_list
  • oci_core_service_gateway
  • oci_core_subnet
  • oci_core_vcn
  • oci_core_vlan
  • oci_core_virtual_circuit
  • oci_core_vnic_attachment
  • oci_core_volume_attachment
  • oci_core_volume_backup
  • oci_core_volume_backup_policy
  • oci_core_volume_backup_policy_assignment
  • oci_core_volume_group
  • oci_core_volume_group_backup
  • oci_core_volume

data_safe

  • oci_data_safe_data_safe_private_endpoint

database

  • oci_database_autonomous_container_database
  • oci_database_autonomous_database
  • oci_database_autonomous_exadata_infrastructure
  • oci_database_autonomous_vm_cluster
  • oci_database_backup_destination
  • oci_database_backup
  • oci_database_database
  • oci_database_db_home
  • oci_database_db_system
  • oci_database_exadata_infrastructure
  • oci_database_vm_cluster_network
  • oci_database_vm_cluster

datacatalog

  • oci_datacatalog_catalog
  • oci_datacatalog_data_asset
  • oci_datacatalog_connection
  • oci_datacatalog_catalog_private_endpoint

dataflow

  • oci_dataflow_application

datascience

  • oci_datascience_project
  • oci_datascience_notebook_session
  • oci_datascience_model
  • oci_datascience_model_provenance

dataintegration

  • oci_dataintegration_workspace

dns

  • oci_dns_zone
  • oci_dns_steering_policy
  • oci_dns_steering_policy_attachment
  • oci_dns_tsig_key
  • oci_dns_rrset

email

  • oci_email_suppression
  • oci_email_sender

events

  • oci_events_rule

file_storage

  • oci_file_storage_file_system
  • oci_file_storage_mount_target
  • oci_file_storage_export
  • oci_file_storage_snapshot

functions

  • oci_functions_application
  • oci_functions_function

health_checks

  • oci_health_checks_http_monitor
  • oci_health_checks_ping_monitor

identity

  • oci_identity_api_key
  • oci_identity_authentication_policy
  • oci_identity_auth_token
  • oci_identity_compartment
  • oci_identity_customer_secret_key
  • oci_identity_dynamic_group
  • oci_identity_group
  • oci_identity_identity_provider
  • oci_identity_idp_group_mapping
  • oci_identity_policy
  • oci_identity_smtp_credential
  • oci_identity_swift_password
  • oci_identity_ui_password
  • oci_identity_user_group_membership
  • oci_identity_user
  • oci_identity_network_source

integration

  • oci_integration_integration_instance

kms

  • oci_kms_key
  • oci_kms_key_version
  • oci_kms_vault

limits

  • oci_limits_quota

load_balancer

  • oci_load_balancer_backend
  • oci_load_balancer_backend_set
  • oci_load_balancer_certificate
  • oci_load_balancer_hostname
  • oci_load_balancer_listener
  • oci_load_balancer_load_balancer
  • oci_load_balancer_path_route_set
  • oci_load_balancer_rule_set

marketplace

  • oci_marketplace_accepted_agreement

monitoring

  • oci_monitoring_alarm

mysql

  • oci_mysql_mysql_backup
  • oci_mysql_mysql_db_system

nosql

  • oci_nosql_table
  • oci_nosql_index

object_storage

  • oci_objectstorage_bucket
  • oci_objectstorage_object_lifecycle_policy
  • oci_objectstorage_object
  • oci_objectstorage_preauthrequest
  • oci_objectstorage_replication_policy

oce

  • oci_oce_oce_instance

ocvp

  • oci_ocvp_sddc
  • oci_ocvp_esxi_host

oda

  • oci_oda_oda_instance

ons

  • oci_ons_notification_topic
  • oci_ons_subscription

osmanagement

  • oci_osmanagement_managed_instance_group
  • oci_osmanagement_software_source

streaming

  • oci_streaming_connect_harness
  • oci_streaming_stream_pool
  • oci_streaming_stream

tagging

  • oci_identity_tag_default
  • oci_identity_tag_namespace
  • oci_identity_tag

waas

  • oci_waas_address_list
  • oci_waas_custom_protection_rule
  • oci_waas_http_redirect
  • oci_waas_waas_policy