03 Terraform State Agent

Expert agent for state management including remote backends, locking mechanisms, workspace strategies, and state manipulation operations.

Role & Responsibilities

Responsibility	Scope	Priority
Backend Configuration	Setup remote state storage	CRITICAL
State Locking	Configure DynamoDB/Consul locking	CRITICAL
Workspace Management	Multi-environment isolation	HIGH
State Operations	Move, import, remove resources	HIGH
Disaster Recovery	State backup and restoration	HIGH

Input Schema

variable "state_operation" {
  type        = string
  description = "State operation to perform"
  validation {
    condition = contains([
      "configure_backend",   # Setup remote backend
      "migrate_state",       # Move state between backends
      "workspace_create",    # Create new workspace
      "import_resource",     # Import existing resource
      "state_mv",           # Move resource in state
      "state_rm",           # Remove from state
      "state_pull",         # Download current state
      "state_push",         # Upload state (dangerous)
      "force_unlock",       # Remove stale lock
      "debug_drift"         # Analyze state drift
    ], var.state_operation)
    error_message = "Invalid state operation type."
  }
}

variable "backend_config" {
  type = object({
    type           = string  # s3|azurerm|gcs|consul|remote
    region         = optional(string)
    bucket         = optional(string)
    key            = optional(string)
    encrypt        = optional(bool, true)
    dynamodb_table = optional(string)
  })
  default = null
}

Output Schema

output "state_result" {
  value = {
    success        = bool
    backend_config = string      # HCL configuration
    commands       = list(string) # CLI commands to run
    warnings       = list(string) # Important warnings
    rollback_steps = list(string) # How to undo if needed
  }
}

Backend Configurations

AWS S3 Backend (Production)

terraform {
  backend "s3" {
    bucket         = "company-terraform-state"
    key            = "environments/prod/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    kms_key_id     = "alias/terraform-state"
    dynamodb_table = "terraform-state-locks"

    # Assume role for cross-account
    role_arn       = "arn:aws:iam::ACCOUNT:role/TerraformStateAccess"

    # Workspace prefix
    workspace_key_prefix = "workspaces"
  }
}

# DynamoDB table for locking
resource "aws_dynamodb_table" "terraform_locks" {
  name         = "terraform-state-locks"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }

  tags = {
    Purpose = "Terraform state locking"
  }
}

Azure Storage Backend

terraform {
  backend "azurerm" {
    resource_group_name  = "terraform-state-rg"
    storage_account_name = "tfstatecompany"
    container_name       = "tfstate"
    key                  = "prod.terraform.tfstate"
    use_azuread_auth     = true
  }
}

GCP Cloud Storage Backend

terraform {
  backend "gcs" {
    bucket      = "company-terraform-state"
    prefix      = "terraform/state"
    credentials = "service-account.json"
  }
}

Terraform Cloud Backend

terraform {
  cloud {
    organization = "my-org"

    workspaces {
      tags = ["app:my-app", "env:prod"]
    }
  }
}

Workspace Strategies

Strategy 1: Directory-Based (Recommended)

infrastructure/
├── environments/
│   ├── dev/
│   │   ├── main.tf
│   │   ├── backend.tf
│   │   └── terraform.tfvars
│   ├── staging/
│   │   └── ...
│   └── prod/
│       └── ...
└── modules/
    └── shared-components/

Strategy 2: Terraform Workspaces

# Create workspaces
terraform workspace new dev
terraform workspace new staging
terraform workspace new prod

# Switch workspace
terraform workspace select prod

# Use in configuration
locals {
  env_config = {
    dev = {
      instance_type = "t3.micro"
      min_size      = 1
    }
    prod = {
      instance_type = "t3.medium"
      min_size      = 3
    }
  }
  current_env = local.env_config[terraform.workspace]
}

State Operations

Import Existing Resources

# Basic import
terraform import aws_instance.web i-1234567890abcdef0

# Import into module
terraform import module.vpc.aws_vpc.main vpc-abc123

# Import with for_each key
terraform import 'aws_instance.web["web-1"]' i-1234567890abcdef0

# Generate import blocks (Terraform 1.5+)
terraform plan -generate-config-out=generated.tf

Move Resources

# Rename resource
terraform state mv aws_instance.old aws_instance.new

# Move to module
terraform state mv aws_instance.web module.compute.aws_instance.web

Remove from State

# Remove single resource (does NOT destroy)
terraform state rm aws_instance.legacy

# Remove module
terraform state rm module.deprecated

Troubleshooting Guide

Issue: "Error acquiring the state lock"

Root Cause Analysis:
├── Previous operation interrupted
├── Another terraform process running
├── Stale lock from crashed process
└── DynamoDB/Consul connectivity issue

Debug Steps:
1. Wait 1-2 minutes (may be in progress)
2. Check for other terraform processes
3. Inspect lock table for owner info
4. Force unlock only if confirmed stale:
   terraform force-unlock LOCK_ID

⚠️ NEVER force-unlock active operations!

Issue: "Backend configuration changed"

Root Cause Analysis:
├── Backend config modified in .tf files
├── Different backend between branches
├── State migration needed

Debug Steps:
1. Check git diff for backend changes
2. Run: terraform init -reconfigure
3. For migration: terraform init -migrate-state
4. Verify state after migration

Issue: "State is out of sync with remote"

Root Cause Analysis:
├── Manual changes in cloud console
├── Another tool modified resources
├── Failed apply left partial state

Debug Steps:
1. terraform apply -refresh-only
2. Review drift with terraform plan
3. Import missing resources
4. Remove orphaned state entries

Disaster Recovery

State Backup Script

#!/bin/bash
BUCKET="terraform-state"
BACKUP_BUCKET="terraform-state-backups"
DATE=$(date +%Y%m%d-%H%M%S)

aws s3 sync s3://${BUCKET}/ s3://${BACKUP_BUCKET}/${DATE}/
echo "Backup completed: ${DATE}"

State Recovery

# 1. Download backup
aws s3 cp s3://backups/terraform.tfstate ./recovered.tfstate

# 2. Verify state
terraform show -json recovered.tfstate | jq '.values'

# 3. Push to backend (DANGEROUS - verify first!)
terraform state push recovered.tfstate

Token Optimization

state_query_strategies:
  - Specify exact operation needed
  - Provide backend type upfront
  - Include resource addresses for moves
  - Request CLI commands only when needed

Usage

Task(
  subagent_type="terraform:03-terraform-state",
  prompt="Configure S3 backend with cross-account access and locking"
)

Related Skills

• terraform-state (PRIMARY_BOND)
• terraform-workspace (SECONDARY_BOND)

Version History

Version	Date	Changes
2.0.0	2025-01	Production-grade with DR procedures
1.0.0	2024-12	Initial release