Terraform

--- name: terraform description: Design and manage infrastructure as code with Terraform — modules, remote state (S3 + DynamoDB), Stacks (deployments), test framework, preconditions/postconditions, moved/removed blocks, and CI/CD plan/apply separation. Use when user asks to write Terraform config, set up remote state, design modules, manage state, or automate infrastructure. Do NOT use for Kubernetes (use kubernetes), Docker (use docker), or CI/CD pipeline design (use ci-cd). triggers: - "Terraform" - "infrastructure as code" - "IaC" - "terraform plan" - "terraform apply" - "terraform state" - "remote backend" - "provision infrastructure" - "cloud resources" - "AWS infrastructure" - "HashiCorp" - "terraform module" negatives: - "Kubernetes" - "Docker" - "CI/CD" - "Ansible" - "Pulumi" - "CloudFormation" license: MIT compatibility: opencode metadata: workflow: infrastructure audience: devops version: "2.0.0"

Terraform Architect

Design infrastructure as code with Terraform 1.10+ features: Stacks, test framework, provider-defined functions, and state management.

Workflow

Step 1: Determine project structure

Step 2: Bootstrap remote backend

# backend.tf
terraform {
  backend "s3" {
    bucket         = "tf-state-{account}-{region}"
    key            = "{env}/{component}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "tf-state-lock"
  }
  required_version = ">= 1.10"
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}

Step 3: Design modules

Single responsibility: one module = one domain.

modules/
├ networking/
│   main.tf, variables.tf, outputs.tf
├ compute/
│   main.tf, variables.tf, outputs.tf
└ database/
    main.tf, variables.tf, outputs.tf
environments/
├ prod/
│   backend.tf -> key = "prod/compute/terraform.tfstate"
│   main.tf       module "compute" { source = "../../modules/compute" }
│   terraform.tfvars
└ dev/

Step 4: Use preconditions/postconditions

resource "aws_db_instance" "main" {
  allocated_storage = 100
  engine = "postgres"
  engine_version = "16.3"
  instance_class = "db.r6g.large"

  lifecycle {
    postcondition {
      condition     = self.engine == "postgres"
      error_message = "Only PostgreSQL is supported"
    }
  }
}

data "aws_iam_policy_document" "example" {
  statement {
    actions = ["s3:GetObject"]

    condition {
      test     = "Bool"
      variable = "aws:SecureTransport"
      values   = ["true"]
    }

    condition {
      test     = "IpAddress"
      variable = "aws:SourceIp"
      values   = var.allowed_ips
    }
  }

  lifecycle {
    precondition {
      condition     = length(var.allowed_ips) > 0
      error_message = "At least one allowed IP must be specified"
    }
  }
}

Step 5: Use moved and removed blocks for refactoring

# Instead of manual state mv, code-review it:
moved {
  from = aws_s3_bucket.old
  to   = module.storage.aws_s3_bucket.main
}

# To remove a resource from state without destroying it:
removed {
  from = aws_instance.legacy
  lifecycle {
    destroy = false  # Keep the resource alive
  }
}

Terraform Stacks (2025+)

Stacks enable deployment of multiple configurations with shared state:

# stacks/stack.hcl
stack "dev" {
  source = "./infrastructure"
  path   = "dev"
}

stack "prod" {
  source = "./infrastructure"
  path   = "prod"
}

Provider-defined Functions (1.10+)

# Built-in providers now expose functions
result = provider::aws::arn_parse("arn:aws:s3:::my-bucket")
# or
result = provider::aws::arn_build("s3", "my-bucket", "", "us-east-1")

Testing Framework

# tests/example.tftest.hcl
run "create_bucket" {
  command = apply
  variables {
    bucket_name = "test-bucket-${run_id}"
  }
  assert {
    condition     = aws_s3_bucket.main.bucket == "test-bucket-${run_id}"
    error_message = "Bucket name mismatch"
  }
}

run "verify_encryption" {
  command = apply
  assert {
    condition     = aws_s3_bucket.main.server_side_encryption_configuration[0].rule[0].apply_server_side_encryption_by_default[0].sse_algorithm == "AES256"
    error_message = "Bucket must have AES256 encryption"
  }
}

terraform test

State Management Rules

Provider Caching (CI speedup)

export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"

# Share cache across projects
mkdir -p $TF_PLUGIN_CACHE_DIR

CI/CD Pipeline

name: Terraform
on: [pull_request, push]
jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform fmt -check
      - run: terraform validate
      - run: terraform plan -out=tfplan
      - uses: actions/upload-artifact@v4
        with: { name: tfplan, path: tfplan }

  apply:
    if: github.ref == 'refs/heads/main'
    needs: [plan]
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - uses: actions/download-artifact@v4
        with: { name: tfplan }
      - run: terraform apply tfplan

Emergency State Surgery

Production Checklist

• Remote backend S3 + DynamoDB locking
• KMS encryption on state bucket
• Versioning enabled on state bucket
• Public access blocked on state bucket
• Per-environment state isolation
• Per-component state files
• State access IAM roles (least privilege)
• Plan on PR, apply only from CI
• concurrency prevents simultaneous applies
• terraform validate + fmt -check in CI
• Module versions pinned (not latest)
• Secrets as sensitive = true on outputs
• No secrets in state (Vault / AWS Secrets Manager)

Anti-Patterns

Plan Review Format (Required)

When reviewing terraform plan output, verify these checks:

Error Handling

State Surgery

# List resources in state
terraform state list

# Show specific resource
terraform state show aws_instance.web

# Move resource between state files
terraform state mv -state-out=prod.tfstate aws_instance.web aws_instance.web

# Remove resource from state (keeps real resource)
terraform state rm aws_instance.old_server

# Import existing resource into state
terraform import aws_instance.web i-1234567890abcdef0

Provider Pinning Strategy

terraform {
  required_providers {
    aws = { source = "hashicorp/aws"; version = "~> 5.0" }
    kubernetes = { source = "hashicorp/kubernetes"; version = ">= 2.20, < 3.0" }
  }
}

Rules: ~> for minor updates (5.0-5.x). >= X, < Y for explicit ranges. Never latest.

Cost Estimation

# Infracost (open source)
infracost breakdown --path . --format table

# Terraform Cloud cost estimation (paid)
# Enabled automatically in Terraform Cloud workspaces

# Manual: cost per resource type
# EC2: instance_type * hours * region_price
# RDS: instance_class * hours + storage_gb * 0.115
# S3: gb_stored * 0.023 + requests * 0.0004

# Tag for cost allocation
resource "aws_instance" "web" {
  tags = { CostCenter = "engineering", Environment = "production" }
}

Sources

• Terraform Documentation (developer.hashicorp.com/terraform)
• Terraform Stacks — HCP documentation
• Terraform Test Framework — developer.hashicorp.com
• HashiCorp Learn: moved blocks
• AWS Well-Architected IaC patterns
• Gruntwork — Terraform best practices

Pre-Apply Checklist

Before terraform apply:

• terraform fmt -recursive passes — all files consistently formatted
• terraform validate passes — syntax and reference errors caught
• terraform plan reviewed — no unexpected resource replacements
• Stateful resources (RDS, S3, disks) have prevent_destroy = true in lifecycle block
• Remote backend configured with state locking (DynamoDB for S3, etc.)
• Provider versions pinned (~> X.Y or exact version), never latest
• Preconditions/postconditions on critical resources (e.g., condition = var.instance_count > 0)
• moved blocks for renamed resources (never terraform state mv manually)
• Sensitive outputs marked with sensitive = true
• Plan file reviewed by a second person for production changes
• terraform apply runs from CI/CD, not a developer laptop

Checklist

• Skill loads without errors in the AI agent
• YAML frontmatter is valid (description, compatibility, audience)
• Workflow section provides clear step-by-step instructions
• Error handling section covers common failure modes
• All referenced files (references/, scripts/, assets/) exist
• Skill triggers correctly for intended use cases
• No broken links or missing resources