Configuring the Provider

Configure the OCI Terraform provider with the required authentication and optional environment variables.

Note

For examples of Terraform configuration files for creating specific resources, see Terraform Oracle Cloud Infrastructure Provider Examples.

Authentication

To interact with the Oracle Cloud Infrastructure (OCI) services and supported resources, configure the OCI Terraform provider with authentication credentials for an OCI account.

The OCI Terraform provider supports four authentication methods:

API Key Authentication

By default, the Terraform provider uses API Key authentication, but you can specify this explicitly by setting the auth attribute to "APIKey" in the provider definition. Calls to OCI using API Key authentication require that you provide the following credentials:

tenancy_ocid - OCID of the tenancy. To get the value, see Where to Get the Tenancy's OCID and User's OCID.
user_ocid - OCID of the user calling the API. To get the value, see Where to Get the Tenancy's OCID and User's OCID.
private_key - The contents of the private key file. Required if private_key_path isn't defined, and takes precedence over private_key_path if both are defined. For details on how to create and configure keys see How to Generate an API Signing Key and How to Upload the Public Key.
private_key_path - The path (including filename) of the private key stored on the computer. Required if private_key isn't defined. For details on how to create and configure keys see How to Generate an API Signing Key and How to Upload the Public Key.
private_key_password - (Optional) Passphrase used for the key, if it's encrypted.
fingerprint - Fingerprint for the key pair being used. To get the value, see How to Get the Key's Fingerprint.
region - An OCI region. See Regions and Availability Domains.
config_file_profile - The profile name if you would like to use a custom profile in the OCI config file to provide the authentication credentials. See Using the SDK and CLI Configuration File for more information.

For example, provide these values as either environment variables or inside Terraform configuration variables.

Instance Principal Authorization

Note

Instance principal authorization applies only to instances that are running in Oracle Cloud Infrastructure.

Use instance principal authorization to remove requirements for the following attributes in the provider definition:

tenancy_ocid
user_ocid
private_key_path
fingerprint

When instance principal authorization is enabled, the provider can make API calls from a compute instance without these attributes.

To enable instance principal authorization for OCI Terraform providers, set the auth attribute to "InstancePrincipal" in the provider definition, as shown in the following example:

variable "region" {}

provider "oci" {
   auth = "InstancePrincipal"
   region = var.region
}

For more information, see Calling Services from an Instance.

Resource Principal Authorization

Resource principal authorization, such as instance principal authorization, allows the provider to make API calls without needing to provide credentials within the provider definition. Resource principal authorization is used to allow resources such as a running function to access other Oracle Cloud Infrastructure resources. For more information, see Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.

To enable resource principal authorization for OCI Terraform providers:

Create the dynamic group and policies required for the running function to manage other OCI resources. Follow the instructions in Using the Console under Accessing Other Oracle Cloud Infrastructure Resources from Running Functions and ensure that the policy allows management of other resources.
Set the following environment variables:
- OCI_RESOURCE_PRINCIPAL_VERSION, containing the value 2.2.
  
  When the value is 1, region override isn't supported.
- OCI_RESOURCE_PRINCIPAL_RPST, containing the raw contents of the rpst file or the absolute path to the rpst file, including the filename.
- OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM, containing the absolute path to the private.pem file (including the filename).
- OCI_RESOURCE_PRINCIPAL_REGION, containing the region identifier in which the provider is deployed (for example, us-phoenix-1).
Set the auth attribute to "ResourcePrincipal" in the provider definition.

Note

The value for region in the provider block overrides the region value set by the environment variable OCI_RESOURCE_PRINCIPAL_REGION. This change, introduced in Terraform Provider version 5.0.0, isn't downward-compatible.

When the value of the OCI_RESOURCE_PRINCIPAL_VERSION environment variable is 1, region override isn't supported.

Example:
```
provider "oci" {
   auth = "ResourcePrincipal"
   region = var.region
}
```

Security Token Authentication

Run Terraform using a token generated with Token-based Authentication for the CLI. To enable Security Token authentication, update the provider definition as follows:

Set the auth attribute to SecurityToken.
Provide a value for config_file_profile.
Set the region.

For example:

# Configure the Oracle Cloud Infrastructure provider to use Security Token authentication
provider "oci" {
  auth = "SecurityToken"
  config_file_profile = "PROFILE"
  region = var.region
}

Important

This token expires after one hour. Avoid using this authentication method when provisioning of resources takes longer than one hour. For more information, see Refreshing a Token.

OKE Workload Identity Authentication

In Kubernetes, a workload is an application running on a Kubernetes cluster. A workload can be one application component running inside a single pod, or several application components running inside a set of pods that work together. All the pods in the workload run in the same namespace.

In Oracle Cloud Infrastructure, a workload running on a Kubernetes cluster managed by Kubernetes Engine (also known as OKE) is considered a resource in its own right. A workload resource is identified by the unique combination of Kubernetes cluster, namespace, and service account. This unique combination is referred to as the workload identity.

OKE Workload Identity Authentication allows workloads running on Kubernetes clusters managed by Kubernetes Engine to access other Oracle Cloud Infrastructure resources. For more information, see Granting Workloads Access to OCI Resources.

To enable OKE Workload Identity Authentication for OCI Terraform providers, set the auth attribute to "OKEWorkloadIdentity" in your provider definition, as shown in the following example:

variable "region" {}
provider "oci" {
   auth = "OKEWorkloadIdentity"
   region = var.region
}

Environment Variables

The following environment variables are available for configuring the provider.

OCI_DEFAULT_CERTS_PATH (certificate path)

Note

Use only one certificate path variable at a time.
OCI_SDK_APPEND_USER_AGENT (custom user agent)
realm_specific_service_endpoint_template_enabled (dedicated endpoint to securely access storage buckets)
TF_APPEND_USER_AGENT (custom user agent)
TF_VAR_compartment_ocid (compartment OCID authentication value)
TF_VAR_fingerprint (key fingerprint authentication value)
TF_VAR_private_key_path (private key path authentication value)
TF_VAR_region (region value)

Example: us-ashburn-1
TF_VAR_tenancy_ocid (tenancy OCID authentication value)
TF_VAR_user_ocid (user OCID authentication value)
USER_AGENT_PROVIDER_NAME (custom user agent)

Exporting and Sourcing Environment Variables

You can either export the required authentication values as environment variables, or source them in different bash profiles when executing Terraform commands.

If you primarily work in a single compartment, consider exporting the compartment OCID as an environment variable. The tenancy OCID is also the OCID of the root compartment, and can be used where any compartment OCID is required.

Tip

You can remove Terraform configuration file provider blocks if all API Key Authentication required values are provided as environment variables or are set in a *.tfvars file.

UNIX and Linux Export Example

The following UNIX and Linux bash_profile example applies when the Terraform configuration is limited to a single compartment or user.

export OCI_DEFAULT_CERTS_PATH=<certificates_path>
export TF_VAR_tenancy_ocid=<tenancy_OCID>
export TF_VAR_compartment_ocid=<compartment_OCID>
export TF_VAR_user_ocid=<user_OCID>
export TF_VAR_fingerprint=<key_fingerprint>
export TF_VAR_private_key_path=<private_key_path>
export TF_VAR_region=<region>
export USER_AGENT_PROVIDER_NAME=<custom_user_agent>
export OCI_SDK_APPEND_USER_AGENT=<custom_user_agent>
export TF_APPEND_USER_AGENT=<custom_user_agent>

After setting these values, open a new terminal or source the profile changes:

$ source ~/.bash_profile

For more complex environments, consider maintaining multiple sets of environment variables.

Windows Export Example

Note

Ensure PEM format for keys. For more information, see How to Generate an API Signing Key.

The following Windows example applies when the Terraform configuration is limited to a single compartment or user.

setx OCI_DEFAULT_CERTS_PATH=<certificates_path>
setx TF_VAR_tenancy_ocid <tenancy_OCID>
setx TF_VAR_compartment_ocid <compartment_OCID>
setx TF_VAR_user_ocid <user_OCID>
setx TF_VAR_fingerprint <key_fingerprint>
setx TF_VAR_private_key_path <private_key_path>
setx TF_VAR_region=<region>
setx USER_AGENT_PROVIDER_NAME=<custom_user_agent>
setx OCI_SDK_APPEND_USER_AGENT=<custom_user_agent>
setx TF_APPEND_USER_AGENT=<custom_user_agent>

After setting these values, exit and reopen the terminal. (The variables aren't set for the current session.)

Using Custom User Agents

To use a custom user agent, export one of the following environment variables. Only one environment variable is considered at a time, following this priority order:

USER_AGENT_PROVIDER_NAME
OCI_SDK_APPEND_USER_AGENT
TF_APPEND_USER_AGENT

Specifying a Dedicated Endpoint for the Object Storage Service

Securely access storage buckets in Object Storage with dedicated endpoints using the OCI Terraform provider. When configuring the provider, use an environment variable, a parameter in the provider block, or both. If you use both, the provider block parameter takes precedence.

The environment variable is OCI_REALM_SPECIFIC_SERVICE_ENDPOINT_TEMPLATE_ENABLED. Default value is false. Set the value to true to use a dedicated endpoint.

The provider block parameter is realm_specific_service_endpoint_template_enabled. Default value is false. Set the value to true to use a dedicated endpoint.

Using a Dedicated Endpoint Only

In the provider block, set realm_specific_service_endpoint_template_enabled to true.
```
provider "oci" {
  realm_specific_service_endpoint_template_enabled = true
}
```

Using Both Default and Dedicated Endpoints

Use the Terraform alias meta-argument to access both default service endpoints and realm-specific endpoints. Override default endpoints with realm-specific endpoints by specifying the provider parameter in resource creation.

Define a provider block for each endpoint.

provider "oci" {
  realm_specific_service_endpoint_template_enabled = true
}

provider "oci" {
    #By default realm_specific_service_endpoint_template_enabled = false
}

Use the Terraform alias meta-argument in the provider block that's for a dedicated endpoint.

For example, add alias = "custom_endpoint".

provider "oci" {
  alias = "custom_endpoint"
  realm_specific_service_endpoint_template_enabled = true
}

provider "oci" {
    #By default realm_specific_service_endpoint_template_enabled = false
}

In each resource block that you want to use a dedicated endpoint, reference the provider by the alias value.

For example, add provider = "custom_endpoint".

The following example shows two provider blocks and two resource blocks. In this example, bucket1 uses the default endpoint while bucket2 uses the dedicated endpoint.

provider "oci" {
  alias = "custom_endpoint"
  realm_specific_service_endpoint_template_enabled = true
}

provider "oci" {
    #By default realm_specific_service_endpoint_template_enabled = false
}

resource "oci_objectstorage_bucket" "bucket1" {
  compartment_id = var.compartment_ocid1
  namespace      = var.namspace1
  name           = var.name1
  access_type    = var.access_type1
}

resource "oci_objectstorage_bucket" "bucket2" {
  provider = "oci.custom_endpoint"
  compartment_id = var.compartment_ocid2
  namespace      = var.namspace2
  name           = var.name2
  access_type    = var.access_type2
}

Using the SDK and CLI Configuration File

Important

Parameter names in the SDK and CLI configuration file are slightly different.

You can define the required provider values in the same ~/.oci/config file that the SDKs and CLI use. For details on setting up this configuration, see SDK and CLI Configuration File.

Tip

Terraform configuration file provider blocks can be removed if all API Key Authentication required values are provided as environment variables or are set in the ~/.oci/config file.

To set a nondefault OCI config profile as an environment value, use the following command:

export TF_VAR_config_file_profile=<config_file_profile_name>

You can also set the OCI config profile in a provider block. For example:

provider "oci" {
  tenancy_ocid = var.tenancy_ocid
  config_file_profile= var.config_file_profile
}

Order of Precedence

If the parameters are set in multiple locations, the order of precedence is as follows:

The environment variable
The non-default profile in the OCI config file, if provided
The DEFAULT profile in the OCI config file

Oracle Cloud Infrastructure Documentation