State Backend

This guide shows you how to configure Terraform to use Stategraph as a state backend.

Already have state in S3, GCS, or Terraform Cloud? See State Migration to migrate your existing state to Stategraph.

Prerequisites

Overview

Terraform's HTTP backend stores state via REST API calls. Stategraph implements this API, so you can use it as a drop-in replacement for remote state storage.

Step 1: Create an API Key

  1. Open Stategraph at http://localhost:8080
  2. Log in (via local authentication or OAuth)
  3. Navigate to Settings
  4. In the API Keys section, click Create API Key
  5. Copy the generated token and set it as an environment variable:
export TF_HTTP_USERNAME="session"
export TF_HTTP_PASSWORD="<your-api-key>"

Step 2: Create a State

Create a state in Stategraph before configuring Terraform.

First, configure the CLI (uses the same API key as Terraform):

export STATEGRAPH_API_BASE="http://localhost:8080"
export STATEGRAPH_API_KEY="$TF_HTTP_PASSWORD"

List your tenants to get your tenant ID:

stategraph user tenants list

Output:

550e8400-e29b-41d4-a716-446655440000    my-org

Then create the state:

stategraph states create --tenant 550e8400-e29b-41d4-a716-446655440000 --name "my-project"

The response includes a group_id - copy this for the next step:

{
  "id": "...",
  "name": "my-project",
  "group_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace": "default"
}

Step 3: Configure Terraform Backend

Add the HTTP backend configuration to your Terraform project using the group_id from Step 2:

terraform {
  backend "http" {
    address = "http://localhost:8080/api/v1/states/backend/<group-id>"
    # username and password from TF_HTTP_USERNAME and TF_HTTP_PASSWORD
  }
}

Replace <group-id> with the group_id from Step 2.

Step 4: Initialize Terraform

Initialize Terraform with the new backend:

terraform init

Step 5: Verify

Run a Terraform command to verify the backend is working:

terraform plan
terraform apply

After applying, open Stategraph at http://localhost:8080. You should see your state with:

  • Resource count
  • Last updated timestamp
  • Resource details and dependencies

Next Steps