» Discovering Terraform resources in an Oracle Cloud Infrastructure compartment

» Overview

Beginning with version 3.50, the terraform-oci-provider can be run as a command line tool to discover resources that have been created within Oracle Cloud Infrastructure compartments and generate Terraform configuration files for the discovered resources.

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/

» Prerequisites

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.

By default, the user authentication information is retrieved from a configuration file. For details on setting this up, see SDK and CLI configuration file

In the absence of a configuration file, the authentication information can also 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>

» 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:
    • core - Discovers compute, block storage, and networking resources within the specified compartment
    • database - Discovers database and autonomous database resources within the specified compartment
    • load_balancer - Discovers load balancer resources within the specified compartment
    • tagging - Discovers tag-related resources within the specified compartment
    • identity - Discovers identity resources across the entire tenancy
    • availability_domain - Discovers availability domains used by your compartment-level resources. It is recommended to always specify this value.
  • generate_state - Provide this flag to import the discovered resources into a state file along with the Terraform configuration

Note: The compartment export functionality currently supports discovery of the target compartment. The ability to discover resources in child compartments is not yet supported.

» 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, the generated Terraform configuration will contain a commented line like this:

#admin_password = <<Required attribute not found in discovery>>

Run 'terraform plan' against the generated configuration files to get more information about the missing values.

» 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

identity (tenancy-scope resources)

  • oci_identity_api_key
  • oci_identity_auth_token
  • oci_identity_authentication_policy
  • 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_ui_password
  • oci_identity_user
  • oci_identity_user_group_membership

core (compartment-scope resources)

  • oci_core_boot_volume
  • oci_core_cpe
  • oci_core_cross_connect
  • oci_core_cross_connect_group
  • oci_core_dhcp_options
  • oci_core_drg
  • oci_core_drg_attachment
  • oci_core_image
  • oci_core_instance
  • oci_core_instance_configuration
  • oci_core_instance_pool
  • 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_remote_peering_connection
  • oci_core_route_table
  • oci_core_security_list
  • oci_core_service_gateway
  • oci_core_subnet
  • oci_core_vcn
  • oci_core_virtual_circuit
  • oci_core_vnic_attachment
  • oci_core_volume
  • oci_core_volume_attachment
  • oci_core_volume_backup_policy_assignment
  • oci_core_volume_group

database (compartment-scope resources)

  • oci_database_autonomous_container_database
  • oci_database_autonomous_database
  • oci_database_autonomous_exadata_infrastructure
  • oci_database_db_home
  • oci_database_db_system

load_balancer (compartment-scope resources)

  • 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

object_storage (compartment-scope resources)

  • oci_objectstorage_bucket

tagging (compartment-scope resources)

  • oci_identity_tag
  • oci_identity_tag_default
  • oci_identity_tag_namespace