Terraform: Create Scripts and State Files with Resource Discovery
The OCI resource discovery feature creates Terraform files for existing resources in your compartment. Use it 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.
For additional information, see:
Before You Begin
To successfully perform this tutorial, you must have the following:
- An Oracle Cloud Infrastructure account. See Signing Up for Oracle Cloud Infrastructure.
- A MacOS, Linux, or Windows computer.
- Terraform tutorial resources:
- Go through all the steps in Terraform Tutorial: Set Up Resource Discovery.
- Make a note of the OCI Terraform provider command:
- Cloud Shell:
terraform-provider-oci_<version>
from/usr/bin
- Compute instance or a local environment: Use the
<shorter-alias>
that you created in the previous tutorial to use instead of the command,terraform-provider-oci_<version>
.- Example:
tf-oci
- Example:
- Cloud Shell:
- Terraform v1.1.3+:
- If you're using Cloud Shell, you don't need to install Terraform. Terraform is already installed.
- If you're using a compute instance or a local environment, then in the Terraform Tutorial: Set Up OCI Terraform, go to the Prepare section and follow the Install Terraform steps.
1. Create a Resource
Create a bucket in your tenancy through the Console. This bucket does not have a Terraform script. Later, use resource discovery to create a Terraform script and a state file for the bucket.
If your username is in the Administrators group, then skip this section. Otherwise, have your administrator add the following policy to your tenancy:
allow group <the-group-your-username-belongs> to manage compartments in tenancy
With this privilege, you can create a compartment for all the resources in your tutorial.
- In the top navigation bar, open the Profile menu.
- Click your username.
- In the left pane, click Groups.
- In a notepad, copy the Group Name that your username belongs.
- Open the navigation menu and click Identity & Security. Under Identity, click Policies.
- Select your compartment from the Compartment drop-down.
- Click Create Policy.
- Fill in the following information:
- Name:
manage-compartments
- Description:
Allow the group <the-group-your-username-belongs> to list, create, update, delete and recover compartments in the tenancy.
- Compartment:
<your-tenancy>(root)
- Name:
- For Policy Builder, click Show manual editor.
- Paste in the following policy:
allow group <the-group-your-username-belongs> to manage compartments in tenancy
- Click Create.
Reference: The compartments
resource-type in Verbs + Resource-Type Combinations for IAM
Create a compartment for the resources that you create in this tutorial.
- Sign in to the Oracle Cloud Infrastructure Console.
- Open the navigation menu and click Identity & Security. Under Identity, click Compartments.
- Click Create Compartment.
- Fill in the following information:
- Name:
<your-compartment-name>
- Description:
Compartment for <your-description>.
- Parent Compartment:
<your-tenancy>(root)
- Name:
- Click Create Compartment.
Reference: Create a compartment
If your username is in the Administrators group, then skip this section. Otherwise, have your administrator add the following policy to your tenancy:
allow group <the-group-your-username-belongs> to manage all-resources in compartment <your-compartment-name>
With this privilege, you can manage all resources in your compartment, essentially giving you administrative rights in that compartment.
- Open the navigation menu and click Identity & Security. Under Identity, click Policies.
- Select your compartment from the Compartment drop-down.
- Click Create Policy.
- Fill in the following information:
- Name:
manage-<your-compartment-name>-resources
- Description:
Allow users to list, create, update, and delete resources in <your-compartment-name>.
- Compartment:
<your-tenancy>(root)
- Name:
- For Policy Builder, select the following choices:
- Policy use cases:
Compartment Management
- Common policy templates:
Let compartment admins manage the compartment
- Groups:
<the-group-your-username-belongs>
- Location:
<your-tenancy>(root)
- Policy use cases:
- Click Create.
Reference: Common Policies
Create a bucket in your compartment.
Ensure that you create your bucket in
<your-compartment-name>
.2. Discover the Resource
Discover the bucket that you created in your compartment.
- Go to Terraform Resource Discovery.
- Go to the Usage section.
- From the two command options in the Usage section, use the
one with the
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 are discovering its resources:
-compartment_name=<your-compartment-name>
- Create and then specify a directory for the discovered
resources:
Example:
-output_path=$HOME/resource-discovery
- Use the export command to perform resource discovery:
- Instead of
- 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 quotations 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 does not 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 does not reach the output directory.
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.
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.
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.
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 click Storage. Under Object Storage & Archive Storage, click Buckets.
- In the left panel, for Compartment, select
<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: