Forgecroft Docs
Quickstart Guides Essentials Power Agent API Reference
Core ConceptsCLI ReferenceGo SDKAuthenticationAPI KeysRoles & PermissionsCreating WorkspacesVCS ConnectionsCredentialsState BackendsExecution ModesWorkspace AttributesDependencies & PromotionStacks OverviewCreating StacksEnvironments & VarfilesPromotion GraphManaging StacksRun LifecyclePlan vs ApplyChangesetsApprovalsLogsForce UnlockDrift DetectionTroubleshootingGovernance OverviewPolicy SetsWriting RegoRego PlaygroundApproval RulesExternal ChecksGovernance PreviewGovernance TimelineManaging TeamsNotification ChannelsNotification TargetsUser PreferencesAccess GrantsAudit EventsGitHub AppSlackCredential TypesState Backends
Guides / Workspaces

State Backends

Configure where Terraform state is stored and how it's encrypted.

State backend configs tell Forgecroft where to store and read infrastructure state from.

Backend Types

Forgecroft supports two categories of state backend:

Forgecroft-managed — Forgecroft provisions and owns the storage on your behalf. No bucket or credential setup required. Managed state uses Cloudflare R2 under the hood and is available on all plans. Forgecroft configures the state backend for your workspace during onboarding — you do not need to create a state backend config manually.

Bring-your-own — You own and configure the storage. Forgecroft injects the backend block into your workspace’s Terraform config so you don’t need to commit it to your repo.

TypeDescription
s3Amazon S3, or any S3-compatible store (including Forgecroft-managed R2)
gcsGoogle Cloud Storage
localLocal filesystem (testing only)

Creating a State Backend Config

POST /state-backend-configs
{
  "name": "Production State",
  "backend_type": "s3",
  "bucket": "my-terraform-state",
  "region": "us-east-1",
  "credential_config_id": "cred-uuid"
}
FieldRequiredDescription
nameYesHuman-readable name
backend_typeNos3 (default), gcs, or local
bucketYes for s3/gcsBucket name
regionNoRegion for S3 (omit or use auto for R2)
endpointNoCustom endpoint URL for S3-compatible stores (required for R2)
credential_config_idNoCredential config for backend access
project_idNoScope to a specific project

State Key

The state key is the path within the bucket where state is stored. Set it on the workspace:

PATCH /workspaces/{id}
{ "state_key": "production/vpc" }

If left blank, Forgecroft generates one automatically.

For stacks, the state key is auto-generated as {stack}/{env} (e.g., myapp/dev, myapp/staging).

Backend Credentials

The state backend can use a separate credential config from the cloud provider credentials. This is useful when:

Set state_backend_credential_config_id on the workspace to use a different credential for state access.

State Encryption

For sensitive infrastructure, you can encrypt state at rest:

PATCH /workspaces/{id}
{ "state_encryption_config_id": "enc-uuid" }

The encryption config must be of type state_encryption. Forgecroft manages the encryption passphrase as a Kubernetes Secret with automatic garbage collection.