State Backend Setup

Forgecroft can store Terraform state in your own S3 bucket or GCS bucket. This guide covers what you need to provision on the provider side before creating a state backend config in Forgecroft.

If you want Forgecroft to manage state storage for you, no setup is needed — Forgecroft provisions Cloudflare R2-backed storage automatically.

Amazon S3

Bucket

Create a standard S3 bucket. Enable versioning if you want to recover from accidental state corruption.

IAM Policy

The IAM identity used by your state credential config needs:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-state-bucket",
        "arn:aws:s3:::your-state-bucket/*"
      ]
    }
  ]
}

This can be an IAM user (for aws_static credentials) or an IAM role (for aws_assume_role).

Cloudflare R2 (S3-Compatible)

R2 uses the s3 backend type with a custom endpoint. Set the region to auto:

{
  "name": "R2 State",
  "backend_type": "s3",
  "bucket": "your-r2-bucket",
  "endpoint": "https://<account_id>.r2.cloudflarestorage.com",
  "region": "auto"
}

Use an R2 API token scoped to the specific bucket as your state credential config (credential_type: aws_static, using the R2 token’s access key ID and secret).

Google Cloud Storage

Bucket

Create a GCS bucket. Enable object versioning if you want state recovery.

Service Account Permissions

Grant the service account used by your state credential config the following permissions on the bucket:

• storage.objects.get
• storage.objects.create
• storage.objects.delete
• storage.buckets.get

The predefined role roles/storage.objectAdmin covers all of these.

Uniform Bucket-Level Access

Enable uniform bucket-level access on the bucket. GCS buckets with ACL-based access may reject the backend’s requests.

Credential Separation

Forgecroft supports separate credentials for state access and infrastructure operations on the same workspace. Common reasons:

• The state bucket lives in a different AWS account from the infrastructure being deployed
• The state service account is narrowly scoped to storage only, separate from the deployment role
• Compliance requires auditing state access independently from resource changes

Set state_backend_credential_config_id on the workspace:

PATCH /workspaces/{id}
{ "state_backend_credential_config_id": "cred-uuid" }

If not set, the workspace’s primary credential_config_id is used for both state and infrastructure operations.

Related

• State Backends — Creating state backend configs and the state key convention
• Credential Types — Supported credential types and required secret fields
• Credentials — Managing credential configs