Terraform State Management

Centralized configuration, security protocols, and operational guidelines for managing Aevum Encyclopedia's infrastructure state across all environments.

ℹ️

Scope & Ownership This repository governs infrastructure state for all Aevum Encyclopedia services. State files are strictly versioned, encrypted, and locked. Modifications require PR review and CI validation.

Backend Configuration

All Terraform modules use a remote S3 backend with DynamoDB locking. The backend is initialized during the first terraform init run in CI or via approved local overrides.

backend.tf

terraform {
  backend "s3" {
    bucket         = "aevum-encyclopedia-terraform-state"
    key            = "global/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-lock"
    encrypt        = true
    kms_key_id     = "alias/aevum-infra-tfstate-key"
    acl            = "bucket-owner-full-control"
  }
}

State Locking & Concurrency

DynamoDB handles distributed locking to prevent concurrent modifications. Lock duration defaults to 30s with automatic retries. Manual unlock is restricted to Platform Engineering leads.

Scenario	Behavior	Resolution
CI Pipeline Run	Acquires lock automatically	Retry or wait for pipeline completion
Local Drift Detection	Read-only access (no write lock)	Use `terraform plan` with `-refresh=false`
Stale Lock	Prompt for override	`terraform force-unlock <LOCK_ID>` (requires approval)

⚠️

Critical Security Warning Never commit .tfstate files to version control. State contains plaintext secrets, resource IDs, and sensitive attributes. Aevum state files are encrypted at rest using AWS KMS and in transit via TLS 1.3.

Workspace Strategy

We enforce environment isolation via Terraform workspaces to prevent state collisions and enable safe promotion pipelines.

dev — Experimental changes, temporary resources, short-lived TTLs
staging — Pre-production mirror, integration testing, drift validation
prod — Live Aevum Encyclopedia services, strict guardrails, audit logging

Workspace state paths are automatically routed:

Backend Key Resolution

# terraform workspace new dev
key = "workspaces/dev/terraform.tfstate"

# terraform workspace select prod
key = "workspaces/prod/terraform.tfstate"

State Operations Reference

Common CLI commands used by the infrastructure team. Always run in a clean workspace or CI runner unless explicitly authorized.

Command	Use Case	Risk Level
terraform state list	Inventory managed resources	🟢 Safe
terraform state mv	Refactor module paths without destroying	🟡 Medium
terraform state rm	Orphan external resources (manual cleanup required)	🔴 High
terraform import	Bring existing infrastructure under management	🟡 Medium
terraform state pull	Debug state structure (read-only)	🟢 Safe

🛡️

Compliance & Audit All state modifications are logged to AWS CloudTrail and synced to our SIEM. Monthly state integrity checks run via HashiCorp Sentinel policies. Report drift or anomalies to #platform-infra immediately.