How to manage OpenTofu state with Quake AI S3

By default, OpenTofu stores state in a local terraform.tfstate file. This works for solo development but breaks down when multiple people or CI pipelines need to apply changes to the same infrastructure. Remote state with locking solves this.

Quake AI provides S3-compatible object storage (Swift + Ceph), which works as an OpenTofu S3 backend. This guide shows you how to set it up.

Prerequisites#

• OpenTofu or Terraform installed
• A Quake AI account with S3 credentials (access key and secret key from the dashboard)
• An existing S3 bucket on Quake AI (create one through the dashboard or using the S3 Storage with ACLs template)

Create a state bucket#

If you do not already have a bucket for state, create one through the Quake AI dashboard or the AWS CLI configured for Quake AI:

aws s3 mb s3://my-project-tfstate \
  --endpoint-url https://object.YOUR_REGION.rumble.cloud

Enable versioning on the bucket to protect against accidental state corruption:

aws s3api put-bucket-versioning \
  --bucket my-project-tfstate \
  --versioning-configuration Status=Enabled \
  --endpoint-url https://object.YOUR_REGION.rumble.cloud

Configure the S3 backend#

Add a backend block to your OpenTofu configuration. This typically goes in a backend.tf file:

terraform {
  backend "s3" {
    bucket = "my-project-tfstate"
    key    = "infrastructure/terraform.tfstate"
    region = "us-east-1"

    endpoints = {
      s3 = "https://object.YOUR_REGION.rumble.cloud"
    }

    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
    use_path_style              = true
  }
}

The skip_* flags are required because Quake AI's S3-compatible endpoint does not implement every AWS-specific metadata API. The use_path_style flag ensures bucket names appear in the URL path rather than as subdomains.

Set S3 credentials#

The S3 backend reads credentials from environment variables. Add these alongside your OpenStack credentials:

export AWS_ACCESS_KEY_ID="YOUR_S3_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="YOUR_S3_SECRET_KEY"

Migrate existing local state#

If you already have a local terraform.tfstate file, reinitialize to migrate it to the remote backend:

tofu init -migrate-state

OpenTofu prompts you to confirm the migration. After confirmation, the local state file is copied to the S3 bucket, and future operations read and write state remotely.

Verify the migration by checking the bucket contents:

aws s3 ls s3://my-project-tfstate/infrastructure/ \
  --endpoint-url https://object.YOUR_REGION.rumble.cloud

You should see terraform.tfstate listed.

State locking#

The S3 backend supports state locking through DynamoDB, but Quake AI does not provide a DynamoDB-compatible service. This means concurrent tofu apply operations from different machines could corrupt state.

To mitigate this:

• CI/CD serialization. Configure your CI pipeline to run only one apply at a time (see CI/CD integration)
• Team discipline. Agree that only the CI pipeline applies changes, never individual developers
• State snapshots. Bucket versioning (configured above) lets you recover from corruption by restoring a previous state version

Multiple state files per project#

For larger projects, use separate state files per environment or component. Change the key value in the backend configuration:

# Production
key = "production/terraform.tfstate"

# Staging
key = "staging/terraform.tfstate"

# Networking (shared across environments)
key = "shared/networking.tfstate"

This isolates blast radius: a bad apply in staging cannot corrupt production state.

See also#

• How to get started with Infrastructure as Code on Quake AI
• S3 Storage with ACLs template
• How to manage multiple environments with OpenTofu
• How to integrate OpenTofu with CI/CD