oci

The oci backend stores the Terraform state file in Oracle Cloud Infrastructure (OCI) Object Storage, allowing multiple users to collaborate using a shared remote state and benefit from features such as state locking and workspaces.

⚠️ Warning: It is highly recommended that you enable Bucket Versioning on the object storage bucket to allow for state recovery in the case of accidental deletions and human error.

Example Configuration

terraform {
  backend "oci" {
    # Required
    bucket            = "mybucket"
    namespace         = "my-namespace"
     # Optional
    tenancy_ocid      = "ocid1.tenancy.oc1..xxxxxxx"
    user_ocid         = "ocid1.user.oc1..xxxxxxxx"
    fingerprint       = "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
    private_key_path  = "~/.oci/oci_api_key.pem"
    region            = "us-ashburn-1"
    key               = "path/to/my/key"
    workspace_key_prefix = "envs/"
    kms_key_id        = "ocid1.key.oc1.iad.xxxxxxxxxxxxxx"
    auth              = "APIKey"
    config_file_profile = "DEFAULT"
  }
}

This assumes we have a bucket created called mybucket. The Terraform state is written to the key path/to/my/key.

Note that for the access credentials we recommend using a partial configuration.

State Storage

The oci backend stores Terraform state files in Oracle Cloud Infrastructure (OCI) Object Storage at the path defined by the key parameter, inside the bucket specified by the bucket parameter.

Using the example shown above, the state file would be stored at: path/to/my/key in the bucket mybucket.

When using Terraform workspaces, the state for the default workspace is stored exactly at the path described above. For non-default workspaces, the state is stored using the following path format: <workspace_key_prefix>/<workspace_name>/<key>

• The default workspace_key_prefix is tf-state-env, but it can be customized using the workspace_key_prefix backend parameter.

• For example, with workspace development, the state would be stored at: tf-state-env/development/path/to/my/key

State Locking

• The oci backend supports state locking by leveraging the If-None-Match: * header capability of OCI Object Storage.
• When a user initiates a terraform plan/apply/destroy, the backend creates a lock object in the same bucket as the state file.
• For example, the lock file for the development workspace would be stored at: tf-state-env/development/path/to/my/key.lock

This locking mechanism helps prevent concurrent operations on the same state file, reducing the risk of corruption or conflicting changes.

Permissions Required

OCI Object Storage Bucket Permissions

Terraform requires the following OCI IAM permissions on the target backend bucket to manage the state file and associated lock files:

• OBJECT_INSPECT (includes HeadObject)
• OBJECT_CREATE (includes PutObject, CreateMultipartUpload, UploadPart, and CommitMultipartUpload)
• OBJECT_DELETE (includes DeleteObject)
• OBJECT_READ (includes GetObject)

Alternatively, you can specify the exact operations if you're using fine-grained policies:

• GetObject
• PutObject
• DeleteObject
• HeadObject
• CreateMultipartUpload
• UploadPart
• CommitMultipart

Note: These permissions should be granted on the specific bucket being used for Terraform state storage.

OCI IAM Policy Reference

OCI IAM Policy Reference This resource provides comprehensive details on the required permissions and how to structure your policies to grant Terraform the appropriate access to Object Storage resources.

Data Source Configuration

To make use of the oci remote state in another configuration, use the terraform_remote_state data source.

data "terraform_remote_state" "mystate" {
  backend = "oci"
  config = {
    bucket            = "mybucket"
    key               = "path/to/my/key"
    namespace         = "my-namespace"
    tenancy_ocid      = "ocid1.tenancy.oc1..xxxxxxx"
    user_ocid         = "ocid1.user.oc1..xxxxxxxx"
    fingerprint       = "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
    private_key_path  = "~/.oci/oci_api_key.pem"
    region            = "us-ashburn-1"
  }
}

The terraform_remote_state data source will return all of the root module outputs defined in the referenced remote state (but not any outputs from nested modules unless they are explicitly output again in the root). An example output might look like:

# data.terraform_remote_state.mystate:
data "terraform_remote_state" "mystate" {
    backend = "oci"
    config  = {
        bucket            = "mybucket"
        key               = "path/to/my/key"
        namespace         = "my-namespace"
        tenancy_ocid      = "ocid1.tenancy.oc1..xxxxxxx"
        user_ocid         = "ocid1.user.oc1..xxxxxxxx"
        fingerprint       = "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
        private_key_path  = "~/.oci/oci_api_key.pem"
        region            = "us-ashburn-1"
    }
}

Configuration

The oci backend requires the configuration of the OCI namespace and Object Storage bucket where the Terraform state file will be stored.

Credentials and Shared Configuration

⚠️ Warning: We strongly recommend using environment variables to supply credentials and other sensitive data. Avoid hardcoding these values directly in your configuration or using the -backend-config flag with plaintext secrets.

Sensitive values passed this way may be saved in:

• The .terraform subdirectory
• Terraform plan files (*.tfplan)

For more guidance, refer to the Credentials and Sensitive Data documentation.

Attribute reference

Required Properties

Optional Properties

🔧 Setting Backend Configuration via Environment Variables

You can configure the OCI Terraform backend using environment variables. This provides flexibility and simplifies automation workflows.

For any backend attribute (e.g., region), you can set its value using one of the following environment variable formats:

🧩 Supported Environment Variable Prefixes (in order of priority):

1. OCI_ – OCI SDK-compatible environment variable. Can also be used for Terraform Provider OCI credentials.
   export OCI_region=us-ashburn-1
   
2. No prefix – Generic (lowest priority)
   ```bash
   export region=us-ashburn-1
   Terraform will resolve the attribute value using the first match it finds based on the above priority order.
   

Custom encryption key

To use a custom encryption key, you can generate a new key and its SHA256 hash using the following commands:

1. Generate a 256-bit (32-byte) base64-encoded AES key:

  openssl rand -base64 32

1. Generate the SHA-256 hash of the decoded key:

  generate using command  `echo -n <base64_key> | base64 -d | openssl dgst -sha256 -binary | base64`

Replace <base64_key> with the value generated in step 1.