Terraform at Scale

# Recommended directory structure for a scaled Terraform organisation
# Each directory is a separate root module with its own state file

infrastructure/
├── foundation/                    # Layer 1 — changes rarely, owned by platform team
│   ├── networking/                # VPCs, subnets, peering, Transit Gateway
│   │   ├── versions.tf            # Backend: s3://state/foundation/networking.tfstate
│   │   ├── main.tf
│   │   └── outputs.tf
│   ├── dns/                       # Route53 hosted zones
│   │   └── ...                    # Backend: s3://state/foundation/dns.tfstate
│   └── security/                  # Security groups, WAF, GuardDuty
│       └── ...                    # Backend: s3://state/foundation/security.tfstate
│
├── platform/                      # Layer 2 — changes occasionally, owned by platform team
│   ├── databases/                 # RDS, ElastiCache, DynamoDB tables
│   │   └── ...                    # Backend: s3://state/platform/databases.tfstate
│   └── queues/                    # SQS, SNS, EventBridge
│       └── ...
│
├── services/                      # Layer 3 — changes frequently, owned by app teams
│   ├── payments/                  # Payment service infrastructure
│   │   └── ...                    # Backend: s3://state/services/payments.tfstate
│   └── auth/                      # Auth service infrastructure
│       └── ...                    # Backend: s3://state/services/auth.tfstate
│
└── environments/                  # Per-environment overrides
    ├── dev/
    ├── staging/
    └── prod/

# Key rules:
# 1. Lower layers have no dependencies on higher layers
# 2. Higher layers depend on lower layers via terraform_remote_state or data sources
# 3. Each state file is owned by a single team
# 4. State key naming convention: LAYER/COMPONENT/ENVIRONMENT.tfstate

# In services/payments/versions.tf — configure backend for THIS state file
terraform {
  backend "s3" {
    bucket = "acme-terraform-state"
    key    = "services/payments/terraform.tfstate"
    region = "us-east-1"
  }
}

# Read outputs from the networking state file (a different root module)
data "terraform_remote_state" "networking" {
  backend = "s3"  # Must match the networking module's backend type

  config = {
    bucket = "acme-terraform-state"
    key    = "foundation/networking/terraform.tfstate"  # The OTHER state file
    region = "us-east-1"
  }
}

# Read outputs from the databases state file
data "terraform_remote_state" "databases" {
  backend = "s3"
  config = {
    bucket = "acme-terraform-state"
    key    = "platform/databases/terraform.tfstate"
    region = "us-east-1"
  }
}

# Use the remote outputs — syntax: data.terraform_remote_state.NAME.outputs.OUTPUT_NAME
resource "aws_ecs_service" "payments" {
  name    = "payments-service"
  cluster = aws_ecs_cluster.main.id

  network_configuration {
    # VPC and subnets from the networking module — not hardcoded
    subnets         = data.terraform_remote_state.networking.outputs.private_subnet_ids
    security_groups = [aws_security_group.payments.id]
  }
}

resource "aws_ssm_parameter" "db_endpoint" {
  name  = "/payments/database/endpoint"
  type  = "String"
  # Database endpoint from the platform/databases module
  value = data.terraform_remote_state.databases.outputs.payments_db_endpoint
}

# The networking module's outputs.tf must declare these outputs explicitly:
# output "private_subnet_ids" { value = [for s in aws_subnet.private : s.id] }
# output "vpc_id"             { value = aws_vpc.main.id }
# Without these outputs, terraform_remote_state cannot read them

# Workspaces — what they are
terraform workspace new staging    # Create a new workspace
terraform workspace select prod    # Switch to prod workspace
terraform workspace list           # List all workspaces
terraform workspace show           # Show current workspace name

# What workspaces actually do:
# Each workspace gets its own state file at a different S3 key:
# default:  s3://bucket/key/terraform.tfstate
# staging:  s3://bucket/env:/staging/key/terraform.tfstate
# prod:     s3://bucket/env:/prod/key/terraform.tfstate

# Referencing the workspace name in configuration
locals {
  # Use workspace name to drive environment-specific values
  env_config = {
    dev = {
      instance_type = "t3.micro"
      db_class      = "db.t3.micro"
      min_capacity  = 1
    }
    staging = {
      instance_type = "t3.small"
      db_class      = "db.t3.small"
      min_capacity  = 2
    }
    prod = {
      instance_type = "t3.large"
      db_class      = "db.r6g.large"
      min_capacity  = 3
    }
  }

  config = local.env_config[terraform.workspace]  # terraform.workspace = current name
}

resource "aws_instance" "app" {
  instance_type = local.config.instance_type  # Different per workspace
}

# ── When workspaces ARE appropriate ──────────────────────────────────────────
# - Small teams managing truly identical environments that differ only in size/count
# - Feature branch environments — temporary, short-lived, parallel to main workspace
# - The configuration is simple and all environments use the same AWS account

# ── When workspaces are NOT appropriate ──────────────────────────────────────
# - Different AWS accounts per environment (dev account vs prod account)
#   → workspaces share the same provider configuration — cannot target different accounts
# - Environments with fundamentally different architectures
#   → conditional complexity explodes: if prod needs a NAT gateway but dev does not,
#     the configuration becomes unreadable
# - Large teams where different people manage different environments
#   → no clear ownership — anyone on the team can switch workspaces and apply to prod

# Root terragrunt.hcl — shared config inherited by all child modules
# Located at the root of the infrastructure/ directory

locals {
  account_id  = get_aws_account_id()   # Terragrunt built-in function
  region      = "us-east-1"
  environment = basename(dirname(path_relative_to_include()))  # dev/staging/prod from path
}

# Generate backend configuration dynamically — no more copy-pasting backend blocks
generate "backend" {
  path      = "backend.tf"
  if_exists = "overwrite_terragrunt"

  contents = <