别把 Terraform 模块写成黑盒：IaC 分层设计决策与 6 个生产级反模式拆解

# 反面教材：一个模块管了 VPC + RDS + 安全组 + IAM
module "everything" {
  source = "./modules/everything"
  vpc_cidr         = "10.0.0.0/16"
  rds_engine       = "postgres"
  rds_instance_class = "db.r5.large"
  # ... 还有 38 个变量
}

# modules/vpc/main.tf
# 只管 VPC、子网、路由表、NAT 网关，不碰其他资源

resource "aws_vpc" "this" {
  cidr_block           = var.cidr_block
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = merge(
    local.common_tags,
    { Name = "${var.name_prefix}-vpc" }
  )
}

resource "aws_subnet" "private" {
  for_each = toset(var.private_subnet_cidrs)

  vpc_id            = aws_vpc.this.id
  cidr_block        = each.value
  availability_zone = var.availability_zones[tonumber(regex("[0-9]+$", each.value)) % length(var.availability_zones)]

  tags = merge(
    local.common_tags,
    { Name = "${var.name_prefix}-private-${each.key}", Tier = "private" }
  )
}

resource "aws_route_table" "private" {
  for_each = aws_subnet.private

  vpc_id = aws_vpc.this.id

  route {
    cidr_block     = "0.0.0.0/0"
    nat_gateway_id = aws_nat_gateway.this[each.key].id
  }

  tags = merge(local.common_tags, { Name = "${var.name_prefix}-rt-private-${each.key}" })
}

# modules/eks-platform/main.tf
# 组合 VPC + EKS + 节点组，但不重新定义这些资源

module "vpc" {
  source = "../vpc"

  cidr_block          = var.vpc_cidr
  name_prefix         = var.name_prefix
  availability_zones  = var.availability_zones
  private_subnet_cidrs = var.private_subnet_cidrs
  public_subnet_cidrs  = var.public_subnet_cidrs
}

module "eks" {
  source = "../eks"

  cluster_name       = "${var.name_prefix}-cluster"
  kubernetes_version = var.kubernetes_version
  vpc_id             = module.vpc.vpc_id
  subnet_ids         = module.vpc.private_subnet_ids
  node_groups        = var.node_groups
}

# 输出给环境层使用
output "cluster_endpoint" {
  value = module.eks.cluster_endpoint
}

output "vpc_id" {
  value = module.vpc.vpc_id
}

infrastructure/
├── modules/           # 基础模块
│   ├── vpc/
│   ├── eks/
│   ├── rds/
│   └── alb/
├── compositions/      # 组合模块
│   ├── eks-platform/
│   └── web-stack/
├── envs/              # 环境层
│   ├── dev/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── terraform.tfvars
│   ├── staging/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── terraform.tfvars
│   └── prod/
│       ├── main.tf
│       ├── variables.tf
│       └── terraform.tfvars
└── README.md

# envs/prod/main.tf
terraform {
  required_version = ">= 1.5.0"
  backend "s3" {
    bucket         = "mycompany-tfstate-prod"
    key            = "eks-platform/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "tf-locks-prod"
    encrypt        = true
  }
}

module "platform" {
  source = "../../compositions/eks-platform"

  name_prefix         = "prod"
  vpc_cidr            = "10.10.0.0/16"
  availability_zones  = ["us-east-1a", "us-east-1b", "us-east-1c"]
  kubernetes_version  = "1.30"
  node_groups = {
    general = {
      instance_types = ["m5.large", "m5.xlarge"]
      min_size       = 3
      max_size       = 10
      desired_size   = 5
    }
    spot = {
      instance_types = ["m5.large"]
      min_size       = 0
      max_size       = 20
      desired_size   = 5
      capacity_type  = "spot"
    }
  }
}

# 正确
variable "node_groups" {
  type = map(object({
    instance_types = list(string)
    min_size       = number
    max_size       = number
    desired_size   = number
    capacity_type  = optional(string, "ON_DEMAND")
  }))
  description = "Map of node group configurations. Key is the group name."
}

# 错误：无 type，无 description
variable "node_groups" {
  default = {}
}

variable "enable_deletion_protection" {
  type    = bool
  default = true  # 生产安全默认值
  description = "Whether to enable deletion protection for resources that support it."
}

# 正确：输出使用者需要的标识符
output "vpc_id" {
  value       = aws_vpc.this.id
  description = "The ID of the VPC."
}

output "private_subnet_ids" {
  value       = [for s in aws_subnet.private : s.id]
  description = "List of private subnet IDs."
}

# 错误：输出内部实现细节
output "route_table_private_ids" {
  value = [for rt in aws_route_table.private : rt.id]
}

variable "db_password" {
  type      = string
  sensitive = true
  description = "Master password for the RDS instance."
}

output "db_endpoint" {
  value     = aws_db_instance.this.endpoint
  sensitive = true  # 如果 endpoint 包含敏感信息也标记
}

# 推荐：使用语义化版本约束
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"  # 允许 5.x 的补丁版本更新
}

# 也可以更保守
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.1.2"  # 锁死版本，只手动升级
}

# 不推荐：不锁版本
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  # 没有 version 字段，拉取最新版
}

# envs/dev/terraform.tfvars
name_prefix        = "dev"
vpc_cidr           = "10.20.0.0/16"
availability_zones = ["us-east-1a", "us-east-1b"]
node_groups = {
  general = {
    instance_types = ["t3.medium"]
    min_size       = 1
    max_size       = 3
    desired_size   = 1
  }
}

# envs/prod/terraform.tfvars
name_prefix        = "prod"
vpc_cidr           = "10.10.0.0/16"
availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]
node_groups = {
  general = {
    instance_types = ["m5.large", "m5.xlarge"]
    min_size       = 3
    max_size       = 10
    desired_size   = 5
  }
  spot = {
    instance_types = ["m5.large"]
    min_size       = 0
    max_size       = 20
    desired_size   = 5
    capacity_type  = "spot"
  }
}

# envs/prod/terragrunt.hcl
include "root" {
  path = find_in_parent_folders("root.hcl")
}

terraform {
  source = "../../compositions/eks-platform"
}

inputs = {
  name_prefix        = "prod"
  vpc_cidr           = "10.10.0.0/16"
  availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]
  kubernetes_version = "1.30"
}

# envs/root.hcl - 公共配置
remote_state {
  backend = "s3"
  config = {
    bucket         = "mycompany-tfstate"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "tf-locks"
    encrypt        = true
  }
}

# 反面教材
module "vpc" {
  source = "./modules/vpc"
  enable_vpc          = true
  enable_nat_gateway   = true
  enable_flow_log      = true
  enable_vpn_gateway   = false
  enable_dns           = true
  enable_ipv6          = false
  # ... 还有 20 个 enable_xxx
}

# 修复后
module "vpc" {
  source = "./modules/vpc"
  # 只管 VPC 和子网
  cidr_block = "10.0.0.0/16"
}

module "nat" {
  source     = "./modules/nat-gateway"
  subnet_ids = module.vpc.public_subnet_ids
  # 需要时才引用，不需要就不写这个 block
}

# 反面教材：组合模块直接透传所有变量
module "vpc" {
  source = "../vpc"
  cidr_block                    = var.vpc_cidr_block
  enable_dns_support            = var.vpc_enable_dns_support
  enable_dns_hostnames          = var.vpc_enable_dns_hostnames
  instance_tenancy             = var.vpc_instance_tenancy
  # 把 VPC 模块的 15 个变量全部透传
}

# 修复后：组合模块只暴露业务参数，内部做合理默认
module "vpc" {
  source = "../vpc"

  cidr_block = var.vpc_cidr
  # 其他参数用基础模块的默认值，不透传
}

# 修复：环境层先创建 VPC，再分别传给安全组和路由
module "vpc" {
  source = "../../modules/vpc"
  cidr_block = var.vpc_cidr
}

module "security_group" {
  source  = "../../modules/security-group"
  vpc_id  = module.vpc.vpc_id
  rules   = var.security_group_rules
}

# VPC 模块内部不做安全组关联

# 修复：用 Git ref 锁定版本
module "vpc" {
  source = "git::https://git.mycompany.com/infra/terraform-modules.git//vpc?ref=v1.2.0"

  cidr_block = var.vpc_cidr
}

# envs/prod/main.tf - 独立的 state key
terraform {
  backend "s3" {
    bucket = "mycompany-tfstate-prod"
    key    = "eks-platform/terraform.tfstate"  # 这个 key 是独立的
    region = "us-east-1"
  }
}

# tests/vpc_test.tftest.hcl
run "vpc_creation" {
  command = plan

  variables {
    cidr_block = "10.0.0.0/16"
    name_prefix = "test"
    availability_zones = ["us-east-1a", "us-east-1b"]
  }

  assert {
    condition     = output.vpc_cidr_block == "10.0.0.0/16"
    error_message = "VPC CIDR block does not match input"
  }

  assert {
    condition     = length(output.private_subnet_ids) == 2
    error_message = "Should create 2 private subnets"
  }
}