Terraform Configuration

This guide covers all aspects of configuring Terraform to use Stategraph as a state backend.

HTTP Backend Overview

Stategraph implements Terraform's HTTP backend protocol. This means any Terraform configuration that supports HTTP backends can use Stategraph without modifications.

Basic Configuration

terraform {
  backend "http" {
    address  = "http://stategraph.example.com/api/v1/states/backend/550e8400-e29b-41d4-a716-446655440000"
    username = "session"
    password = "<your-api-key>"
  }
}

Configuration Parameters

URL Structure

http://<host>/api/v1/states/backend/<group_id>

Components

• host: Your Stategraph server address
• group_id: UUID identifier for this state (from state creation)

Authentication Methods

Direct Password

Set the password directly in the configuration:

terraform {
  backend "http" {
    address  = "http://stategraph:8080/api/v1/states/backend/550e8400-e29b-41d4-a716-446655440000"
    username = "session"
    password = "<your-api-key>"
  }
}

Warning: Avoid committing tokens to version control.

Environment Variables

Use Terraform's environment variables for credentials:

export TF_HTTP_USERNAME="session"
export TF_HTTP_PASSWORD="<your-api-key>"

terraform {
  backend "http" {
    address = "http://stategraph:8080/api/v1/states/backend/550e8400-e29b-41d4-a716-446655440000"
    # username and password from environment
  }
}

Partial Configuration

Use partial backend configuration and supply credentials at init time:

# backend.tf
terraform {
  backend "http" {}
}

terraform init \
  -backend-config="address=http://stategraph:8080/api/v1/states/backend/550e8400-e29b-41d4-a716-446655440000" \
  -backend-config="username=session" \
  -backend-config="password=${STATEGRAPH_TOKEN}"

Backend Configuration File

Store configuration in a file:

# backend.hcl
address  = "http://stategraph:8080/api/v1/states/backend/550e8400-e29b-41d4-a716-446655440000"
username = "session"
password = "<your-api-key>"

terraform init -backend-config=backend.hcl

CI/CD Integration

GitHub Actions

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3

      - name: Terraform Init
        env:
          TF_HTTP_USERNAME: session
          TF_HTTP_PASSWORD: ${{ secrets.STATEGRAPH_TOKEN }}
        run: terraform init

      - name: Terraform Plan
        env:
          TF_HTTP_USERNAME: session
          TF_HTTP_PASSWORD: ${{ secrets.STATEGRAPH_TOKEN }}
        run: terraform plan

GitLab CI

terraform:
  image: hashicorp/terraform:latest
  variables:
    TF_HTTP_USERNAME: session
    TF_HTTP_PASSWORD: $STATEGRAPH_TOKEN
  script:
    - terraform init
    - terraform plan

Jenkins

pipeline {
    agent any
    environment {
        TF_HTTP_USERNAME = 'session'
        TF_HTTP_PASSWORD = credentials('stategraph-token')
    }
    stages {
        stage('Terraform') {
            steps {
                sh 'terraform init'
                sh 'terraform plan'
            }
        }
    }
}

Large State Files

For large state files, you may need to adjust timeouts. This is typically done at the HTTP client level or through proxy configuration. Ensure STATEGRAPH_CLIENT_MAX_BODY_SIZE is set appropriately on the server.

Troubleshooting

Backend initialization failed

Error: Failed to get existing workspaces: HTTP error

Solutions: - Verify the Stategraph server is running - Check the URL is correct - Verify network connectivity - Check credentials are valid

Authentication errors

Error: HTTP error: 401 Unauthorized

Solutions: - Verify the API key is correct - Check if the token has expired - Ensure username is set to session

State not found (400 error)

Error: HTTP error: 400

Solutions: - Ensure you created the state in Stategraph first (see State Backend guide) - Verify the group_id in the URL matches the state's group_id

Large state timeouts

If operations fail with timeout errors for large states:

1. Check STATEGRAPH_CLIENT_MAX_BODY_SIZE is set high enough
2. Increase proxy timeouts if using a reverse proxy
3. Consider splitting large states into smaller ones

Best Practices

1. Use environment variables for credentials in CI/CD
2. Create states via API first before configuring Terraform
3. Rotate API keys periodically
4. Monitor state operations using transaction logs

Next Steps

• State Migration - Migrate from other backends
• Transactions - View state history