4. 模块化设计：Terraform Module 的创建、输入输出变量、模块注册中心与版本管理

在跨云资源池编排场景中，直接编写扁平化的 .tf 文件会导致代码膨胀、复用性差、维护成本激增。Terraform Module 是解决这一问题的核心抽象单元，它将一组相关的资源封装为可复用的“乐高积木”。本章将深入 Module 的创建规范、变量契约、注册中心发布流程以及语义化版本控制策略。

4.1 Module 的标准结构与创建规范

Terraform Module 本质上是一个包含 .tf 或 .tf.json 文件的目录。一个生产级 Module 必须遵循以下文件结构约定：

4.2 输入输出变量：定义契约接口

变量是 Module 与外部交互的唯一通道。设计良好的变量接口应遵循“最小暴露原则”与“强类型约束”。

4.2.1 输入变量（Input Variables）

在 variables.tf 中，每个变量应包含 type、description 和可选的 default 与 validation 块。

# variables.tf
variable "cluster_name" {
  description = "Kubernetes 集群名称，全局唯一"
  type        = string
}

variable "node_pool_config" {
  description = "节点池配置映射"
  type = object({
    machine_type = string
    min_count    = number
    max_count    = number
    disk_size_gb = optional(number, 100)
  })
  default = {
    machine_type = "e2-medium"
    min_count    = 1
    max_count    = 3
  }
}

variable "tags" {
  description = "资源标签集合"
  type        = map(string)
  default     = {}
}

4.2.2 输出变量（Output Values）

输出变量用于向调用方暴露关键属性，如集群端点、资源组 ID 等。敏感信息应标记为 sensitive = true。

# outputs.tf
output "cluster_endpoint" {
  description = "API Server 端点地址"
  value       = google_container_cluster.primary.endpoint
}

output "cluster_ca_certificate" {
  description = "集群 CA 证书（Base64 编码）"
  value       = google_container_cluster.primary.master_auth[0].cluster_ca_certificate
  sensitive   = true
}

4.3 模块注册中心与版本管理

企业级跨云资源池需要集中式的模块注册中心来管理模块的发现、发布与版本演进。Terraform 官方提供 Terraform Registry，而私有化场景通常使用 Git 标签 + 文件系统路径 或 私有 Registry（如 Terraform Cloud、HashiCorp Vault 集成方案）。

4.3.1 版本约束语法

在根模块中引用子模块时，必须通过版本约束锁定模块版本，防止意外升级导致资源漂移。

4.3.2 私有 Registry 发布流程

对于使用 Git 仓库作为模块源的团队，推荐采用“语义化版本标签 + 目录路径”的引用方式：

# 根模块引用示例
module "gke_cluster" {
  source = "git::https://gitlab.internal.com/infra-modules/gke-cluster.git?ref=v1.3.1"

  cluster_name    = "prod-app-cluster"
  node_pool_config = {
    machine_type = "n1-standard-4"
    min_count    = 3
    max_count    = 10
  }
  tags = {
    Environment = "production"
    Team        = "platform"
  }
}

4.4 模块化架构全景图

下图展示了从模块创建、注册到跨云消费的完整生命周期，重点突出输入/输出变量在模块间及模块与根配置之间的数据流。

4.5 模块化设计检查清单

在将 Module 发布到注册中心前，请逐项核对以下清单，确保模块质量满足跨云资源池的复用要求：

• 变量完整性：所有输入变量均包含 type、description，敏感变量标记 sensitive。
• 输出最小化：只暴露调用方真正需要的属性，避免输出内部临时资源 ID。
• 版本锁定：versions.tf 中指定 Terraform 与 Provider 的版本下限。
• 示例可运行：examples/ 目录下的示例可通过 terraform init && terraform plan 验证。
• 语义化标签：Git 标签严格遵循 vMAJOR.MINOR.PATCH 格式，并附带 CHANGELOG。
• 跨云兼容：若模块支持多云，需在 README 中明确标注支持的 Provider 版本与 Region 限制。