Using Object Storage for State Files
You can store Terraform state files in Oracle Cloud Infrastructure (OCI) Object Storage. Doing so requires that you configure a backend using one of the Terraform backend types.
Terraform supports various backend types to allow flexibility in how state files are loaded into Terraform. (For more information, see Terraform Backend Types.) For our purposes, we address two of these approaches:
Using an HTTP Backend
Using the HTTP backend type allows you to store state using a simple REST client. With the HTTP backend type, you can easily fetch, update, and purge state using the HTTP
GET
, POST
, and DELETE
methods.
To configure the HTTP backend to store your OCI Terraform state files, do the following:
Create a Pre-Authenticated Request
Creating a pre-authenticated request in Oracle Object Storage enables accessing a bucket or object in the OCI without needing to provide credentials. To do so, you must create a pre-authenticated request that has read/write permissions to the object store where you intend to save the Terraform state file. You can do so in any of three ways: by using the Console UI, by using the command line interface (CLI), or by using the REST APIs.
A state file must exist in the bucket before you create the pre-authenticated request. This file can be an existing state file, or an empty file for the initial state.
For guidance, see Using Pre-Authenticated Requests.
Upload Existing State
If you have an existing state file, you can upload it using Curl to make an
HTTP
PUT
request to the object store URL, as shown here:
curl -X PUT -H "Content-Type: text/plain" --data-binary "@path/to/local/tfstate" http://<prefix>/<my-access-uri>
Configure HTTP as a Terraform Backend
The HTTP backend type stores state using a
simple REST client and allows you to easily fetch, update, and purge state using the
HTTP
GET
, POST
, and DELETE
methods.
The access URI for addressing OCI
Terraform configurations must be of the form :
https://objectstorage.us-phoenix-1.oraclecloud.com/my-access-uri
(where region and access URI are specific to you).
For more example configuration and state files that reference code, and a summary of configuration variables, see Standard Backends: HTTP.
Following is an example Terraform configuration. The region in the URL can be something other than the Phoenix region.
terraform {
backend "http" {
address = "https://objectstorage.us-phoenix-1.oraclecloud.com/<my-access-uri>"
update_method = "PUT"
}
}
Reinitialize Terraform
Finally, you must reinitialize Terraform and then run the apply
command:
terraform init
terraform apply
After completing these steps, you are able to use Oracle Cloud Infrastructure as the backend for storing Terraform state files.
Using an S3-Compatible Backend
Configuring the S3-compatible backend requires that the account be enabled with S3 authentication keys, which are set on a per-user basis.
- Open the navigation menu and click Identity & Security. Under Identity, click Users. Under User Details, click Customer Secret Key. For guidance, see Working with Customer Secret Keys.
-
Set the location for the credentials file. The default location is
~/.aws/credentials
. You can set an alternate location by using the S3 backendshared_credentials_file
option.Caution
Never set theaccess_key
and thesecret_key
attributes in the same Terraform backend configuration, since this creates a security risk. -
Configure the
[default]
entry in the credentials file with the appropriate object storage credentials. The file can contain any number of credential profiles. If you provide a different profile name, you must also update the backendprofile
option in your Terraform configuration file.Following is an example of Object Storage credentials:
[default] aws_access_key_id=ocid1.credential.oc1..exampleuniqueID aws_secret_access_key=mSTdaWhlbWj3ty4JZXlm0NUZV52xlImWjayJLJ6OH9A=
Where
aws_access_key_id
andaws_secret_access_key
are user-specific values provided from the Console. The key values provided in the example are not valid and provided as examples only. -
Set the object storage
endpoint
value in the following format:https://<namespace>.compat.objectstorage.<region>.oraclecloud.com
-
Reinitialize Terraform and then run the
apply
command:terraform init terraform apply
Following is a full example of an Object Storage backend configuration:
terraform {
backend "s3" {
bucket = "terraform-states"
key = "networking/terraform.tfstate"
region = "us-phoenix-1"
endpoint = "https://acme.compat.objectstorage.us-phoenix-1.oraclecloud.com"
shared_credentials_file = "../terraform-states_bucket_credentials"
skip_region_validation = true
skip_credentials_validation = true
skip_metadata_api_check = true
force_path_style = true
}
}
If the same bucket is used across multiple Terraform configurations, the key must be
unique to avoid overwriting the state file. This example uses a single bucket
(terraform-states
) to store all Terraform state files, but uses
a unique prefix for the object name based on the resource
(networking
).
Once you have configured the backend, you must run terraform init
to finish the setup. If you already have an existing terraform.tfstate
file, then Terraform prompts you to confirm that the current state file is the one to upload to the remote state.
The S3 backend configuration can also be used for the
terraform_remote_state
data source to enable sharing state across
Terraform projects.