How to Use DigitalOcean Spaces as a Terraform Remote State Backend

Terraform is an open-source tool that allows you to build, version, and automate the deployment of cloud infrastructure. You can use Terraform to set up basic or complex architectures for your applications.

DigitalOcean Terraform Provider Reference

A complete reference for the DigitalOcean Terraform provider.

By default, Terraform stores state files locally in the directory where Terraform is run. This works well if you’re using Terraform on your own, but it becomes a problem in a team environment where multiple people need to access the state files.

With remote state, instead of keeping the state files on your own machine, Terraform stores them in a central location that everyone on your team can access.

Prerequisites

This guide requires the following resources:

• A Spaces bucket. For instructions, follow How to Create a Spaces Bucket.
• A Spaces access key and secret key. For instructions, follow Sharing Access to Buckets with Access Keys.

Set the Access Key Environment Variables

You can pass your Spaces access key to Terraform in multiple ways. We strongly recommend using environment variables.

Other methods, like using terraform init -backend-config or hardcoding key values in the backend configuration, cause Terraform to include those values in your .terraform folder and plan files, potentially leaking your credentials. Using environment variables helps keep your key private.

Terraform uses AWS_... environment variables for all S3-compatible backend providers. Export your keys to your current shell environment. In Bash shells, for example, use export:

export AWS_ACCESS_KEY_ID="<your_access_key>"
export AWS_SECRET_ACCESS_KEY="<your_secret_key>"

Replace the <your_access_key> and <your_secret_key> placeholders with your actual keys.

Configure the Backend

The following Terraform configuration sets up an s3 backend and configures it to use a DigitalOcean Spaces bucket. You need Terraform version 1.6.3 or higher to use it.

terraform {
required_version = ">= 1.6.3"

  backend "s3" {
    endpoints = {
      s3 = "https://<your_bucket_region>.digitaloceanspaces.com"
    }

    bucket = "<your_bucket_name>"
    key    = "<state_file_name>"

    # Deactivate a few AWS-specific checks
    skip_credentials_validation = true
    skip_requesting_account_id  = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
    skip_s3_checksum            = true
    region                      = "us-east-1"
  }
}

There are three settings to update:

• s3: Update <your_bucket_region> with the region of your bucket. For example, a bucket in the NYC3 datacenter has the URL https://nyc3.digitaloceanspaces.com here.
• bucket: Change <your_bucket_name> to the name of your bucket.
• key: This is the key (or filename) your Terraform state is stored under. Change <state_file_name> to the key you’d like to use. In many S3-compatible clients, these are treated as file paths and can contain forward slashes (/) for directories and periods for file extensions. For example, a value of test/example.tfstate would place an example.tfstate file inside the test directory in the root of your bucket.

Update these variables, then save your configuration in a .tf file.

Initialize and Apply the Terraform Configuration

You can apply this Terraform configuration as is, but it only sets up the bucket as a backend. At this point, add configuration for any additional resources you want to manage. See our Terraform Reference for information on creating DigitalOcean resources using Terraform.

Once your backend and any optional resources are configured, initialize the configuration using the terraform init command:

terraform init

Terraform outputs some status messages indicating that the backend is configured:

Initializing the backend...

Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.

...

Terraform has been successfully initialized!

You may now create the plan and apply the changes:

terraform plan
terraform apply

The terraform apply command updates your resources to match the plan and then saves its state to your Spaces bucket. Any collaborators with the same configuration and access to the bucket are able to use your shared state when applying their own changes.

Use State Locking with Spaces

In Terraform, state locking is a mechanism that prevents multiple concurrent operations from modifying the state file simultaneously. Without state locking, running multiple Terraform processes concurrently could lead to state corruption, resulting in infrastructure drift, inconsistent deployments, or failed updates.

Before Terraform performs operations that modify the state file, it attempts to acquire a lock. If another process has already acquired the lock, Terraform waits until the lock is released before proceeding. If the lock cannot be acquired, Terraform fails with an error.

To lock state in a DigitalOcean Spaces bucket, Terraform must create a lock file in the same bucket as the state file. To enable Spaces state locking, add use_lockfile = true to your Terraform configuration:

terraform {
required_version = "~> 1.11"

  backend "s3" {
    endpoints = {
      s3 = "https://<your_bucket_region>.digitaloceanspaces.com"
    }

    bucket = "<your_bucket_name>"
    key    = "<state_file_name>"

    # Deactivate a few AWS-specific checks
    skip_credentials_validation = true
    skip_requesting_account_id  = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
    skip_s3_checksum            = true
    region                      = "us-east-1"

    # Enable state locking with a lockfile
    use_lockfile                = true
  }
}