Set Up OCI Terraform

Before You Begin

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

An Oracle Cloud Infrastructure account. See Request and Manage Free Oracle Cloud Promotions.
A MacOS, Linux, or Windows environment:

Note

This tutorial uses an Oracle Linux VM environment with an AMD shape for its examples, but you can use any environment mentioned in this section.

1. Prepare

Prepare your environment for authenticating and running Terraform scripts. Also, gather the information your account needs to authenticate the scripts.

Install Terraform

This tutorial suggests that you install the latest version of Terraform that's supported for OCI Resource Manager. Resource Manager is a service for creating Terraform templates for OCI resources. In case you want to use Resource Manager with your Terraform scripts later, then your Terraform version is supported.

In your environment, check the Terraform version.
```
terraform -v
```
If you don't have the latest supported Terraform version, then install the latest supported version using the following steps.
From a browser, go to HashiCorp List of Terraform Versions.
Select the folder with the latest supported Terraform version.

Example: terraform_1.5.7
Copy the name of the zip file that matches your environment into a notepad.

terraform_<version>_<your_environment>.zip

Example for an Oracle 64-bit Linux AMD environment: terraform_1.5.7_linux_amd64.zip
In your environment, create a temp directory and change to that directory:
```
mkdir temp
```
```
cd temp
```
Download the Terraform zip file:
```
wget https://releases.hashicorp.com/terraform/<version>/terraform_<version>_<your_environment>.zip
```
Tip

You can construct the URL by copying the address from the browser. Note that <version> doesn't include the word terraform.

Example:
```
wget https://releases.hashicorp.com/terraform/1.5.7/terraform_1.5.7_linux_amd64.zip
```
If you see a connection error, and you're on VPN, check your proxy settings. See Troubleshooting.
Unzip the file. Example:
```
unzip terraform_1.5.7_linux_amd64.zip
```
Move the unzipped folder to a folder that contains the binaries of the third-party apps that you install. For example, for Oracle Linux, move the unzipped folder to /usr/local/bin:
```
sudo mv terraform /usr/local/bin
```
Go back to your home directory:
```
cd
```
Check the Terraform version:
```
terraform -v
```
Example: Terraform v1.5.7 on linux_amd64

Disregard any message indicating that the version of Terraform is out of date. The important thing is to use the latest supported Terraform version.

You have now successfully installed Terraform.

Create RSA Keys

You create RSA keys for API signing in to your Oracle Cloud Infrastructure account.

Note

Skip creating RSA keys if:

You're using Cloud Shell or Resource Manager. You're already authenticated when you sign in to the Oracle Cloud Console.
You already created RSA keys for the tutorial Set Up Resource Discovery.

Open a terminal window.
Under your home directory, make an .oci directory.
```
mkdir <your-home-directory>/.oci
```
Example for Oracle Linux:
```
mkdir /home/opc/.oci
```
Note

If you're using Windows Subsystem for Linux (WSL), create the /.oci directory directly in the Linux environment. If you create the /.oci directory in a /mnt folder (Windows file system), you're required to use the chmod command to change permissions for the WSL configuration files.

Generate a 2048-bit private key in a PEM format:

openssl genrsa -out <your-home-directory>/.oci/<your-rsa-key-name>.pem 2048

Change permissions, so only you can read and write to the private key file:
```
chmod 600 <your-home-directory>/.oci/<your-rsa-key-name>.pem
```

Generate the public key:

openssl rsa -pubout -in <your-home-directory>/.oci/<your-rsa-key-name>.pem -out $HOME/.oci/<your-rsa-key-name>_public.pem

Copy the public key.

In the terminal, enter:

cat <your-home-directory>/.oci/<your-rsa-key-name>_public.pem

Example (excerpt):

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTFqF...
...
-----END PUBLIC KEY——

Add the public key to your user account.
1. Sign in to the Oracle Cloud Console.
2. In the navigation bar, select the Profile menu and then select User settings or My profile, depending on the option that you see.
3. Select API keys.
4. Select Add API key.
5. Select Paste a public key.
6. Paste the value from the previous step, including the lines with BEGIN PUBLIC KEY and END PUBLIC KEY.
7. Select Add.
  The Configuration file preview dialog box opens. Example:
```
[DEFAULT]
user=ocid1.user.oc1..exampleid
fingerprint=exampleid
tenancy=ocid1.tenancy.oc1..exampleid
region=us-ashburn-1
key_file=<path to your private keyfile> # TODO
```
8. Select Copy, then paste into your notepad.
  The configuration file preview includes information you'll need later, such as tenancy and user OCIDs, fingerprint, and region.

You have now set up the RSA keys to connect to your OCI account.

Reference: How to Generate an API Signing Key

Add List 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-that-your-username-belongs-to> to read all-resources in tenancy

With this privilege, you can list all the resources in your tenancy.

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: list-resources
- Description: Allow the group <a-group-that-your-username-belongs-to> to list the resources in this tenancy.
- Compartment: <your-tenancy>(root)
For Policy Builder, select Show manual editor.

Paste in the following policy:

allow group <a-group-that-your-username-belongs-to> to read all-resources in tenancy

Select Create.

Reference: Common Policies

Gather Required Information

Prepare the information you need to authenticate your Terraform scripts and copy the information into a notepad.

Collect the path to the private key that you added at Create RSA Keys.

Example for Oracle Linux: /home/opc/.oci/<your-rsa-key-name>.pem
Collect the user OCID, fingerprint, tenancy OCID, and region from the API key you added at Create RSA Keys. (You might have this in your notepad already.)
1. Sign in to the Oracle Cloud Console.
2. In the navigation bar, select the Profile menu and then select User settings or My profile, depending on the option that you see.
3. Select API keys.
4. Find the API key that you added at Create RSA Keys.
5. From the Actions menu for the key, select View configuration file.
  The Configuration file preview dialog box opens. Example:
```
[DEFAULT]
user=ocid1.user.oc1..exampleid
fingerprint=xx:xx:xx...xx
tenancy=ocid1.tenancy.oc1..exampleid
region=us-ashburn-1
key_file=<path to your private keyfile> # TODO
```
6. Select Copy, then paste into your notepad.

2. Create Scripts

Create scripts for authentication, to fetch data from your account, and to print outputs.

Add API Key-Based Authentication

First, set up a directory for Terraform scripts. Then add a provider script so your OCI account can authenticate the scripts running from this directory. Finally, add a versions script containing a required_providers block to declare required provider versions.

In <your-home-directory>, create a directory called tf-provider and change to that directory.
```
mkdir tf-provider
```
```
cd tf-provider
```
Create a file called provider.tf.

Add the following code to provider.tf:

Replace the fields with brackets with information you collected at Gather Required Information.
Add quotation marks around string values.

provider "oci" {
  tenancy_ocid = "<tenancy-ocid>"
  user_ocid = "<user-ocid>" 
  private_key_path = "<rsa-private-key-path>"
  fingerprint = "<fingerprint>"
  region = "<region-identifier>"
}

Save the provider.tf file.
In the same directory, create a file called versions.tf.

Add the following code to versions.tf:

terraform {
  required_providers {
    oci = {
      source  = "oracle/oci"
      version = ">=4.67.3"
    }
  }
  required_version = ">= 1.0.0"
}

Save the versions.tf file.

Explanation

Add a Data Source

In this section, you fetch a list of the availability domains in your tenancy. By fetching data, you confirm that your OCI account authenticates your provider.tf script and you get information from your account.

In the tf-provider directory, create a file called availability-domains.tf.

Important

Ensure that all the *.tf files are in the same directory. Terraform processes all the files in a directory in the correct order, based on their relationship. (For a modular approach and future reuse, put provider information in a separate file from other scripts.)
Add the following code to availability-domains.tf, replacing the field with brackets, with information from Gather Required Information.
```
# Source from https://registry.terraform.io/providers/oracle/oci/latest/docs/data-sources/identity_availability_domains

# Tenancy is the root or parent to all compartments.
# For this tutorial, use the value of <tenancy-ocid> for the compartment OCID.

data "oci_identity_availability_domains" "ads" {
  compartment_id = "<tenancy-ocid>"
}
```
Note

The data source gets a list of availability domains in your entire tenancy. The tenancy is the compartment OCID for the root compartment. Providing a specific "<compartment-ocid>" or the "<tenancy-ocid>" outputs the same list.

Explanation

Add Outputs

The data source oci_identity_availability_domains, fetches a list of availability domains. In this section, you declare an output block to print the fetched information.

In the tf-provider directory, create a file called outputs.tf.

Add the following code to outputs.tf.

# Output the "list" of all availability domains.
output "all-availability-domains-in-your-tenancy" {
  value = data.oci_identity_availability_domains.ads.availability_domains
}

Save the outputs.tf file.

Important

Ensure that all the *.tf files are in the same directory. Terraform processes all the files in a directory in the correct order, based on their relationship.

Explanation

3. Run Scripts

Run your Terraform scripts. After your account authenticates the scripts, Terraform fetches your tenancy's availability domains.

Initialize

Initialize a working directory in the tf-provider directory.

Run the Terraform init command.
```
terraform init
```
Example output:
```
Initializing the backend...

Initializing provider plugins...

Terraform has been successfully initialized!
```
If you see a connection error or "failed to query" error, and you're on VPN, check your proxy settings. See Troubleshooting.
Check the contents of the tf-provider directory.
```
ls -a
```

You now have a folder called .terraform that includes the plugins for the oci provider.

Plan

Create an execution plan to check whether the changes shown in the execution plan match your expectations, without changing the real resources.

Run the Terraform plan command.

terraform plan

Example output:

data.oci_identity_availability_domains.ads: Reading...
data.oci_identity_availability_domains.ads: Read complete after 1s [id=xxx]

Changes to Outputs:
  + all-availability-domains-in-your-tenancy = [
      + {
          + compartment_id = "ocid1.tenancy.oc1..xxx"
          + id             = "ocid1.availabilitydomain.xxx"
          + name           = "QnsC:US-ASHBURN-AD-1"
        },
      + {
          + compartment_id = "ocid1.tenancy.oc1..xxx"
          + id             = "ocid1.availabilitydomain.yyy"
          + name           = "QnsC:US-ASHBURN-AD-2"
        },
      + {
          + compartment_id = "ocid1.tenancy.oc1..xxx"
          + id             = "ocid1.availabilitydomain.zzz"
          + name           = "QnsC:US-ASHBURN-AD-3"
        },
    ]

You can apply this plan to save these new output values to the Terraform state, without changing any real
infrastructure.

Note

You're fetching data, so the plan shows that you're only adding outputs. You're not adding, changing, or destroying any resources.

You're using the output.tf file instead of the -out option, so you can ignore the following message:

Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform
apply" now.

Apply

Run your Terraform scripts and get your outputs:
```
terraform apply
```

When prompted for confirmation, enter yes.

After you run the apply command, the output is displayed in the terminal.

Example output:

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

all-availability-domains-in-your-tenancy = tolist([
  {
    "compartment_id" = "ocid1.tenancy.xxx"
    "id" = "ocid1.availabilitydomain.xxx"
    "name" = "QnsC:US-ASHBURN-AD-1"
  },
  {
    "compartment_id" = "ocid1.tenancy.xxx"
    "id" = "ocid1.availabilitydomain.xxx"
    "name" = "QnsC:US-ASHBURN-AD-2"
  },
  {
    "compartment_id" = "ocid1.tenancy.xxx"
    "id" = "ocid1.availabilitydomain.xxx"
    "name" = "QnsC:US-ASHBURN-AD-3"
  },
])

Congratulations! Your Oracle Cloud Infrastructure account can now authenticate your Oracle Cloud Infrastructure Terraform provider scripts.

References:

Troubleshooting

You might encounter the following error messages while running your Terraform scripts.

401 Errors - (Service error:NotAuthenticated)

One of the following variables has an incorrect value:

Tenancy OCID
User OCID
Fingerprint
RSA private key (the path or the key)

In the provider.tf file, double-check the variable names and their values.

provider "oci" {
  tenancy_ocid = "<tenancy-ocid>"
  user_ocid = "<user-ocid>" 
  private_key_path = "<rsa-private-key-path>"
  fingerprint = "<fingerprint>"
  region = "<region-identifier>"
}

Update the variables or their values as needed.
Ensure that you added quotation marks around string values.
Run the scripts.

Can not create client, bad configuration: did not find a proper configuration for private key

The Terraform scripts can't find the RSA private key.

Repeat the steps for creating RSA keys and use the updated key.
Ensure that in the provider.tf file, the variable describing the RSA is called private_key_path.
private_key_path = "<rsa-private-key-path>"
Ensure the path to the RSA private key in the provider.tf file is correct. For example, ensure that the path starts with a slash and has the correct name for the private key, <your-rsa-key-name>.pem
Remove environment variables from the <rsa-private-key-path>.

For example, in the provider.tf file, instead of $HOME/.oci/<rsa-private-key-path>, use /home/opc/<rsa-private-key-path>.

Note

If you're using Windows Subsystem for Linux (WSL), create the /.oci directory directly in the Linux environment. If you create the /.oci directory in a /mnt folder (Windows file system), you're required to use the chmod command to change permissions for the WSL configuration files.

No such host

The region identifier has an incorrect value.

In the Console navigation bar, find your region.
See Working in Regions.
In the table at Regions and Availability Domains, find your region's <region-identifier>. Example: us-ashburn-1.
In the provider.tf file, update the value for <region-identifier> and try again.

Failed to query available provider packages

If you're on a VPN, check the proxy settings.

Disconnect from VPN.
Connect to your VM or your environment without the VPN and run the following Terraform scripts.
```
terraform init
terraform plan
terraform apply
```
If you don't get an error message, then the VPN proxy settings are causing the error.
Consult with your administrator, update the proxy settings, and try again.

What's Next

For the next Terraform: Get Started tutorial, go to:

Create a Compartment

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

Oracle Cloud Infrastructure Documentation Try Free Tier

Set Up OCI Terraform

Before You Begin 🔗

1. Prepare 🔗

2. Create Scripts 🔗

3. Run Scripts 🔗

401 Errors - (Service error:NotAuthenticated)

Can not create client, bad configuration: did not find a proper configuration for private key

No such host

Failed to query available provider packages

What's Next 🔗

Oracle Cloud Infrastructure Documentation
Try Free Tier

Before You Begin

1. Prepare

2. Create Scripts

3. Run Scripts

What's Next