Create Scripts and State Files with Resource Discovery

Generate Terraform files for existing resources in your compartment.

Use the OCI resource discovery feature to:

Create state files for existing resources in the Console, and then add those resources to a Terraform setup.
Duplicate your existing infrastructure in a new tenancy or region.
Detect state drift for updated resources.

In this tutorial, you create scripts and state files for resources in your account through the resource discovery feature. Then you use Terraform to manage the resources.

Key tasks include how to:

Create a resource through the Console.
Create scripts and a state file for the resource through the resource discovery feature.
Update the resource with Terraform.
Confirm that the resource has been updated in the Console.

A diagram of a user connected from a local environment to an Oracle Cloud Infrastructure tenancy. The local environment is Linux and has Terraform OCI Provider binaries installed. There is an arrow from the local environment connected to Terraform Registry in the cloud. There is a second arrow from the local environment sending a message to the user's Oracle Cloud Infrastructure tenancy labeled Authenticate?. The third arrow is from the tenancy to the local environment labeled Fetch Data, Create Scripts, and Create a State File. These arrows suggest that the user has set up their OCI provider variables to be authenticated by their tenancy. The user can then fetch information from the tenancy, and create scripts and state files, by using Terraform OCI provider commands and Terraform Registry. The tenancy contains a bucket with the name rd-bucket, in a compartment called rd-compartment. Resource Discovery is fetching information about this bucket, to create Terraform scripts and a state file in the user's environment.

For more information, see:

Before You Begin

To successfully perform this tutorial, you must have the following:

Requirements

1. Create a Resource

Create a bucket in your tenancy through the Console. This bucket doesn't have a Terraform script. Later, use resource discovery to create a Terraform script and a state file for the bucket.

Add Compartment Policy

If your username is in the Administrators group, then skip this section. Otherwise, ask your administrator to add the following policy to your tenancy:

allow group <a-group-your-username-belongs-to> to manage compartments in tenancy

With this privilege, you can create a compartment for all the resources in your tutorial.

Steps to Add the Policy

Sign in to the Oracle Cloud Console.
In the navigation bar, select the Profile menu and then select User settings or My profile, depending on the option that you see.
Select Groups or My groups, depending on the option that you see.
In a notepad, copy the name of a group that your username belongs to.
Open the navigation menu and select Identity & Security. Under Identity, select Policies.
Select the compartment: <your-tenancy>(root)
Select Create Policy.
On the Create Policy page, enter the following values:
- Name: manage-compartments
- Description: Allow the group <a-group-your-username-belongs-to> to list, create, update, delete and recover compartments in the tenancy.
- Compartment: <your-tenancy>(root)
For Policy Builder, select Show manual editor.

Paste in the following policy:

allow group <a-group-your-username-belongs-to> to manage compartments in tenancy

Select Create.

Reference: Details for Verbs + Resource-Type Combinations (see the compartments resource-type)

Create a Compartment

Add Resource Policy

If your username is in the Administrators group, then skip this section. Otherwise, ask your administrator to add the following policy to your tenancy:

allow group <a-group-your-username-belongs-to> to manage all-resources in compartment <your-compartment-name>

With this privilege, you can manage all resources in your compartment, giving you administrative rights in that compartment.

Steps to Add the Policy

Create a Bucket

2. Discover the Resource

Discover the bucket that you created in your compartment.

Discover the Bucket

From your $HOME directory, delete and re-create the resource-discovery directory you created for the tutorial Set Up Resource Discovery.
```
cd
```
```
rm -R resource-discovery
```
```
mkdir resource-discovery
```

Run the following command:

tf-oci -command=export -compartment_name=<your-compartment-name> -services=object_storage -output_path=$HOME/resource-discovery

Cloud Shell:

terraform-provider-oci_<version> -command=export -compartment_name=<your-compartment-name> -services=object_storage -output_path=$HOME/resource-discovery

Replace <your-compartment-name>, with the name of your compartment.

Sample output:

...
INFO <date> [INFO] ===> Generating resource 'oci_objectstorage_namespace.export_namespace'
INFO <date> [INFO] ===> Generating resource 'oci_objectstorage_bucket.export_<your-bucket-name>'
INFO <date> [INFO] Optional TF attribute 'kms_key_id' not found in source
INFO <date> Found 2 'object_storage' resources. Generated under '/<home-directory>/resource-discovery/object_storage.tf'.
INFO <date> === COMPLETED ===

Note

You might get the following message:

<date> ERROR IN GET: Service error: LifecyclePolicy NotFound. The bucket '<your-bucket-name>' does not define a lifecycle policy.. http status code: 404. Opc request id: iad-1:xxx

Lacking a lifecycle policy is OK for this tutorial. To plan for the service to automatically archive or delete this bucket, see Using Object Lifecycle Management.

Review the generated Terraform scripts.
```
cd resource-discovery
```
```
ls
```
- object_storage.tf
- provider.tf
- vars.tf

View the object_storage.tf script.

cat object_storage.tf

## This configuration was generated by terraform-provider-oci

data oci_objectstorage_namespace export_namespace {
  compartment_id = var.compartment_ocid
}
resource oci_objectstorage_bucket export_<your-bucket-name> {
  access_type    = "NoPublicAccess"
  auto_tiering   = "Disabled"
  compartment_id = var.compartment_ocid
  defined_tags = {
  }
  freeform_tags = {
  }
  #kms_key_id = <<Optional value not found in discovery>>
  metadata = {
  }
  name                  = "<your-bucket-name>"
  namespace             = data.oci_objectstorage_namespace.export_namespace.namespace
  object_events_enabled = "false"
  storage_tier          = "Standard"
  versioning            = "Disabled"
}

You have successfully discovered Object Storage resources in your compartment.

Explanation

Go to Usage (Resource Discovery).
Two command options are listed.

Select the command option that uses compartment_name as a base command:

terraform-provider-oci -command=export -compartment_name=<xxx> -output_path=<xxx>

Update the base command:
- Instead of terraform-provider-oci, use your symbolic link command:
  tf-oci
- Review the Parameter Description section to add proper values to the parameters in the base command:
  - Use the export command to perform resource discovery:
    -command=export
  - Enter the name of the compartment that you're discovering its resources:
    -compartment_name=<your-compartment-name>
  - Create and then specify a directory for the discovered resources:
    Example: -output_path=$HOME/resource-discovery
Add the following parameter from the Parameter Description section to the base command:
- services
From the service names listed for services, use:
- object_storage
- Example: -services=object_storage
- To discover more than one service, separate the service names with a comma.
- Example: -services=object_storage,core
- You don't need quotation marks around the service names.
Construct the command:
Example:
```
tf-oci -command=export -compartment_name=<your-compartment-name> -services=object_storage -output_path=$HOME/resource-discovery
```
Note

Troubleshooting
```
[ERROR] output_path does not exist: stat /$HOME/resource-discovery: no such file or directory
```
The resource discovery command doesn't create a directory for the discovered resources. Create a directory and specify the path in your command.
```
[ERROR] no output directory specified
```
The parser stops at the parameter that lacks a dash. Ensure that you add a dash to the beginning of each parameter. For example, if you use services instead of -services, the parser doesn't reach the output directory.

Generate a State File

To track your resources, Terraform stores the state of your resources in a state file. Then, every time you update a resource with Terraform, Terraform updates the state file with that change.

Run the resource discovery command with the -generate_state flag:

In Cloud Shell:

terraform-provider-oci_<version> -command=export -compartment_id=<tenancy-ocid> -command=export -compartment_name=<your-compartment-name> -services=object_storage -generate_state -output_path=$HOME/resource-discovery

On your compute instance or in your local environment:

tf-oci -command=export -compartment_name=<your-compartment-name> -services=object_storage -generate_state -output_path=$HOME/resource-discovery

Sample output:

...
Terraform has been successfully initialized!
...
Import successful!

The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.

INFO <date> [INFO] ===> Generating resource 'oci_objectstorage_namespace.export_namespace'
INFO <date> [INFO] ===> Generating resource 'oci_objectstorage_bucket.export_<your-bucket-name>'
INFO <date> [INFO] Optional TF attribute 'kms_key_id' not found in source
INFO <date> Found 2 'object_storage' resources. Generated under '/<home-directory>/resource-discovery/object_storage.tf'.
INFO <date> === COMPLETED ===

Note

Troubleshooting:

Error: Failed to query available provider packages:
- If you are on a VPN, check your proxy settings.

View the contents of the resource-discovery directory.
```
ls
```
Sample output:
- object_storage.tf
- provider.tf
- terraform.tfstate
- vars.tf
Note

The resource discovery command overwrites the <resource>.tf files every time you run it. If you don't specify a service, it creates a <resource>.tf file for every resource in the specified compartment.

View the generated Terraform state file.

cat terraform.tfstate

Sample output:

...
"instances": [
  {
      "bucket_id": "ocid1.bucket.xxx",
      "compartment_id": "ocid1.compartment.xxx",
      "created_by": "ocid1.user.xxx",
      "id": "xxx/<your-bucket-name>",
...

Congratulations! You have created a state file for your bucket resource.

References:

3. Update the Resource

Update the name of your bucket in the object_storage.tf file and then run your Terraform scripts. Your account authenticates the scripts and then Terraform updates the bucket name. Confirm the new bucket name through the Console.

Change Bucket Name

In your editor, open the object_storage.tf file and change the bucket name from <your-bucket-name> to <your-bucket-name>-2.

Note

You can only rename empty buckets.

## This configuration was generated by terraform-provider-oci

data oci_objectstorage_namespace export_namespace {
  compartment_id = var.compartment_ocid
}
resource oci_objectstorage_bucket export_<your-bucket-name> {
  access_type    = "NoPublicAccess"
  auto_tiering   = "Disabled"
  compartment_id = var.compartment_ocid
  defined_tags = {
  }
  freeform_tags = {
  }
  #kms_key_id = <<Optional value not found in discovery>>
  metadata = {
  }
  name                  = "<your-bucket-name>-2"
  namespace             = data.oci_objectstorage_namespace.export_namespace.namespace
  object_events_enabled = "false"
  storage_tier          = "Standard"
  versioning            = "Disabled"
}

Save the object_storage.tf file.

Initialize

When you create a state file, resource discovery initializes a working directory that includes Terraform configuration files. Make a habit to run this command every time you update your Terraform scripts.

Check the contents of the resource-discovery directory.
```
ls -a
```
You have a folder called .terraform that includes the plugins for the oci provider.
Confirm that you have Terraform installed.
```
terraform -v
```

Run the init command:

terraform init

Example output:

Initializing the backend...

Initializing provider plugins...
- Using previously-installed hashicorp/oci vx.x.x
...
Terraform has been successfully initialized!

Plan

An execution plan is the list of changes that Terraform plans to apply to your account.

Create an execution plan:
```
terraform plan
```

Review the execution plan.

With the command,terraform plan you check whether the changes shown in the execution plan match your expectations, without changing to the real resources. Example output:

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
-/+ destroy and then create replacement

Terraform will perform the following actions:

  # oci_objectstorage_bucket.export_<your-bucket-name> must be replaced
-/+ resource "oci_objectstorage_bucket" "export_<your-bucket-name>" {
...
    ~ name = "<your-bucket-name>" -> "<your-bucket-name>-2" # forces replacement
        namespace = "<your-tenancy>"
        ...

Plan: 1 to add, 0 to change, 0 to destroy.

Apply

Update the Bucket

Run your Terraform scripts:
```
terraform apply
```
When prompted for confirmation, enter yes, for the bucket name to be replaced.
Example output:
```
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
```

Find New Bucket Name in Console

Open the navigation menu and select Storage. Under Object Storage & Archive Storage, select Buckets.
Select the compartment: <your-compartment-name>.
In the list of buckets, check the bucket name.
The name of the bucket is now <your-bucket-name>-2.

What's Next

Explore other Terraform tutorials:

To explore more information about development with Oracle products, check out these sites:

Oracle Cloud Infrastructure Documentation Try Free Tier

Create Scripts and State Files with Resource Discovery

Before You Begin 🔗

1. Create a Resource 🔗

2. Discover the Resource 🔗

3. Update the Resource 🔗

Update the Bucket

Find New Bucket Name in Console

What's Next 🔗

Oracle Cloud Infrastructure Documentation
Try Free Tier

Before You Begin

1. Create a Resource

2. Discover the Resource

3. Update the Resource

What's Next