terraform-module-library

支持材料可用性

此目录副本包含以下内联指南，但不包含以下支持路径。这些是外部前置条件，不是随附文件：

• <support-root>/assets/vpc-module/
• <support-root>/assets/rds-module/
• <support-root>/references/azure-modules.md
• <support-root>/references/gcp-modules.md

使用依赖这些路径的步骤前，请索取原始支持材料或现有安装；此目录未提供经验证的下载来源。相对于该安装解析每个路径，检查其内容，并验证适用的许可证和执行前置条件。在所需文件存在之前，不要运行命令，也不要声称已遵循所引用的流程。不要伪造缺失的脚本，也不要将名称相同但无关的文件视为等效文件。此处完整记录的独立步骤，可在用户授权范围内继续执行；请报告任何不可用的依赖步骤。

Terraform 模块库

适用于 AWS、Azure 和 GCP 基础设施的生产就绪型 Terraform 模块模式。

以下情况请勿使用此技能

• 任务与 Terraform 模块库无关
• 你需要使用此范围之外的其他领域或工具

说明

• 明确目标、约束和所需输入。
• 应用相关最佳实践并验证结果。
• 提供可执行的步骤和验证方法。

用途

为多个云服务提供商的常见云基础设施模式创建可复用、经过充分测试的 Terraform 模块。

以下情况请使用此技能

• 构建可复用的基础设施组件
• 统一云资源配置
• 实施基础设施即代码最佳实践
• 创建兼容多云的模块
• 建立组织级 Terraform 标准

模块结构

terraform-modules/
├── aws/
│   ├── vpc/
│   ├── eks/
│   ├── rds/
│   └── s3/
├── azure/
│   ├── vnet/
│   ├── aks/
│   └── storage/
└── gcp/
    ├── vpc/
    ├── gke/
    └── cloud-sql/

标准模块模式

module-name/
├── main.tf          # Main resources
├── variables.tf     # Input variables
├── outputs.tf       # Output values
├── versions.tf      # Provider versions
├── README.md        # Documentation
├── examples/        # Usage examples
│   └── complete/
│       ├── main.tf
│       └── variables.tf
└── tests/           # Terratest files
    └── module_test.go

AWS VPC 模块示例

main.tf：

resource "aws_vpc" "main" {
  cidr_block           = var.cidr_block
  enable_dns_hostnames = var.enable_dns_hostnames
  enable_dns_support   = var.enable_dns_support

  tags = merge(
    {
      Name = var.name
    },
    var.tags
  )
}

resource "aws_subnet" "private" {
  count             = length(var.private_subnet_cidrs)
  vpc_id            = aws_vpc.main.id
  cidr_block        = var.private_subnet_cidrs[count.index]
  availability_zone = var.availability_zones[count.index]

  tags = merge(
    {
      Name = "${var.name}-private-${count.index + 1}"
      Tier = "private"
    },
    var.tags
  )
}

resource "aws_internet_gateway" "main" {
  count  = var.create_internet_gateway ? 1 : 0
  vpc_id = aws_vpc.main.id

  tags = merge(
    {
      Name = "${var.name}-igw"
    },
    var.tags
  )
}

variables.tf：

variable "name" {
  description = "Name of the VPC"
  type        = string
}

variable "cidr_block" {
  description = "CIDR block for VPC"
  type        = string
  validation {
    condition     = can(cidrnetmask(var.cidr_block))
    error_message = "CIDR block must be valid IPv4 CIDR notation."
  }
}

variable "availability_zones" {
  description = "List of availability zones"
  type        = list(string)
}

variable "private_subnet_cidrs" {
  description = "CIDR blocks for private subnets"
  type        = list(string)
  default     = []
}

variable "enable_dns_hostnames" {
  description = "Enable DNS hostnames in VPC"
  type        = bool
  default     = true
}

variable "enable_dns_support" {
  type    = bool
  default = true
}

variable "create_internet_gateway" {
  type    = bool
  default = false
}

variable "tags" {
  description = "Additional tags"
  type        = map(string)
  default     = {}
}

outputs.tf：

output "vpc_id" {
  description = "ID of the VPC"
  value       = aws_vpc.main.id
}

output "private_subnet_ids" {
  description = "IDs of private subnets"
  value       = aws_subnet.private[*].id
}

output "vpc_cidr_block" {
  description = "CIDR block of VPC"
  value       = aws_vpc.main.cidr_block
}

最佳实践

1. 使用语义化版本控制管理模块
2. 为所有变量编写说明
3. 在 examples/ 目录中提供示例
4. 使用验证块验证输入
5. 输出重要属性以便组合模块
6. 在 versions.tf 中固定 Provider 版本
7. 使用 locals计算值
8. 使用 count/for_each 实现条件资源
9. 使用 Terratest 测试模块
10. 以一致的方式标记所有资源

模块组合

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

  name               = "production"
  cidr_block         = "10.0.0.0/16"
  availability_zones = ["us-west-2a", "us-west-2b", "us-west-2c"]

  private_subnet_cidrs = [
    "10.0.1.0/24",
    "10.0.2.0/24",
    "10.0.3.0/24"
  ]

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

module "rds" {
  source = "../../modules/aws/rds"

  identifier     = "production-db"
  engine         = "postgres"
  engine_version = "15.3"
  instance_class = "db.t3.large"

  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnet_ids

  tags = {
    Environment = "production"
  }
}

参考文件

• assets/vpc-module/ - 完整的 VPC 模块示例
• assets/rds-module/ - RDS 模块示例
• references/aws-modules.md - AWS 模块模式
• references/azure-modules.md - Azure 模块模式
• references/gcp-modules.md - GCP 模块模式

测试

// tests/vpc_test.go
package test

import (
    "testing"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

func TestVPCModule(t *testing.T) {
    terraformOptions := &terraform.Options{
        TerraformDir: "../examples/complete",
    }

    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)

    vpcID := terraform.Output(t, terraformOptions, "vpc_id")
    assert.NotEmpty(t, vpcID)
}

相关技能

• multi-cloud-architecture - 用于架构决策
• cost-optimization - 用于设计经济高效的方案

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境专属验证、测试或专家审查的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，请暂停并寻求澄清。

此 VPC 片段不会创建路由/NAT 或完整的私有网络。规划前，请验证每个子网 CIDR、确保网段不重叠且位于 VPC 范围内，并确认可用区条目充足；路由表/NAT 决策需要单独设计。无法通过此目录执行 RDS 模块及其他缺失的资源。Terratest InitAndApply/Destroy 会创建/删除可能产生费用的基础设施：请使用获授权的临时账户/工作区、不可变的 Provider/模块版本固定、成本上限，以及由任务负责的清理流程。请确认当前引擎与 Provider 的兼容性，不要将历史版本视为当前建议。