Give Feedback

Configure DigitalOcean Spaces as a Terraform Remote State Backend

Last verified 22 Jun 2026

Spaces Object Storage is an S3-compatible service for storing and serving large amounts of data. The built-in Spaces CDN minimizes page load times, improves performance, and reduces bandwidth and infrastructure costs.

Copy page as Markdown View page as Markdown

Terraform is an open-source tool for building, versioning, and automating cloud infrastructure.

DigitalOcean Terraform Provider Reference

A complete reference for the DigitalOcean Terraform provider.

Terraform stores state locally in the working directory by default. With remote state, Terraform stores state in a shared central location that multiple users or systems can access.

Terraform remote state backend setup requires:

A Spaces bucket.
A Spaces access key and secret key.

Set the Access Key Environment Variables

Terraform supports multiple methods for providing backend credentials. For Spaces, environment variables are the recommended method.

Passing credentials with terraform init -backend-config or defining them directly in backend configuration can write those values to the .terraform directory and plan files. Environment variables reduce that risk.

Set the required AWS_... environment variables for the S3-compatible backend:

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

Replace <your_access_key> and <your_secret_key> with your Spaces credentials.

Configure the Backend

After setting your access key, configure the s3 backend for a DigitalOcean Spaces bucket:

Note

This configuration requires Terraform version 1.6.3 or later.

terraform {
  required_version = ">= 1.6.3"

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

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

    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"
  }
}

The skip_* settings disable AWS-specific validation checks that don’t apply to Spaces.

Update the following values:

s3: Replace <your_bucket_region> with the bucket region. For example, a bucket in the NYC3 datacenter uses https://nyc3.digitaloceanspaces.com.
bucket: Replace <your_bucket_name> with the bucket name.
key: Replace <state_file_name> with the key used to store the Terraform state file.

The key value can include forward slashes (/) and file extensions. For example, test/example.tfstate stores example.tfstate in the test directory at the root of the bucket.

Afterwards, save the configuration in a .tf file.

Initialize and Apply the Terraform Configuration

The backend configuration only defines where Terraform stores state. Additional Terraform resources can be added to the same configuration as needed. For more information on DigitalOcean resources, see the Terraform Reference.

After configuring the backend, initialize the configuration:

terraform init

Terraform returns output confirming 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!

Next, review the proposed infrastructure changes:

terraform plan

Then, apply the planned changes to the configured infrastructure:

terraform apply

After terraform apply runs, Terraform writes state to the Spaces bucket. Any user or system with the same backend configuration and bucket access can use that shared state.

Use State Locking with Spaces

State locking prevents concurrent Terraform operations from modifying the same state file. Before Terraform modifies state, it attempts to acquire a lock. If another process already holds the lock, Terraform waits for the lock to be released. If Terraform can’t acquire the lock, it returns an error.

For a DigitalOcean Spaces backend, Terraform stores the lock file in the same bucket as the state file.

terraform {
  required_version = "~> 1.11"

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

    bucket = "<your_bucket_name>"
    key    = "<state_file_name>"
    
    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"

    use_lockfile                = true
  }
}