3. HCL 进阶：变量与输出、局部值、模块化设计、for_each 与 count 的高级用法

在掌握了 Terraform 基础资源编排后，HCL（HashiCorp Configuration Language）的进阶特性是构建可复用、可维护、可审计的供应链误差预算台账系统的关键。本章将深入解析变量与输出、局部值、模块化设计以及 for_each 与 count 的高级用法，确保你的 IaC 代码具备生产级质量。

3.1 变量与输出：定义供应链台账的输入输出契约

变量（variable）和输出（output）是 Terraform 模块的公共接口。在误差预算台账场景中，变量用于注入环境、预算阈值、通知端点等参数，输出则暴露台账的最终状态或关键指标。

3.1.1 变量定义的最佳实践

属性 用途 供应链台账示例
type 类型约束，防止错误输入 map(string) 定义多环境端点
default 提供安全默认值 error_budget_threshold = 0.95
validation 运行时校验，保障数据质量 检查预算百分比在 0~1 之间
sensitive 标记敏感数据，防止日志泄露 API 、签名密钥 
# variables.tf — 误差预算台账变量定义
variable "environment" {
  description = "部署环境标识，用于隔离台账数据"
  type        = string
  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "环境必须为 dev、staging 或 prod。"
  }
}

variable "error_budget_threshold" {
  description = "SLO 误差预算告警阈值 (0.0 - 1.0)"
  type        = number
  default     = 0.90
  validation {
    condition     = var.error_budget_threshold >= 0 && var.error_budget_threshold <= 1
    error_message = "阈值必须在 0 到 1 之间。"
  }
}

variable "notification_endpoints" {
  description = "告警通知渠道映射"
  type        = map(string)
  default = {
    slack = "https://hooks.slack.com/services/xxx"
    pager = "https://api.pagerduty.com/xxx"
  }
}
供应链安全提示： 对于 sensitive = true 的变量，Terraform 在 plan 和 apply 输出中会将其值标记为 (sensitive value)，避免密钥意外写入 stdout 或日志文件。

3.1.2 输出值：暴露台账关键指标

输出值用于向调用方或 CI/CD 管道暴露台账的核心数据，例如当前预算消耗率、合规状态等。

# outputs.tf — 暴露误差预算台账状态
output "budget_consumption_rate" {
  description = "当前周期误差预算消耗百分比"
  value       = module.error_budget_tracker.consumption_rate
}

output "compliance_status" {
  description = "台账合规状态：OK / WARNING / CRITICAL"
  value       = local.compliance_status
}

output "dashboard_url" {
  description = "台账可视化面板地址"
  value       = "https://monitor.example.com/dashboards/${var.environment}/error-budget"
}

3.2 局部值：消除重复计算，提升可读性

局部值（locals）用于在模块内部定义可复用的表达式，避免在资源块中重复编写相同的逻辑。在误差预算台账中，局部值常用于计算复合标签、派生状态或格式化数据。

# locals.tf — 局部值定义
locals {
  # 统一资源标签，包含环境与项目信息
  common_tags = {
    Project     = "SupplyChain-ErrorBudget"
    Environment = var.environment
    ManagedBy   = "Terraform"
  }

  # 根据预算消耗率计算合规状态
  compliance_status = var.error_budget_consumption > var.error_budget_threshold ? "OK" : (
    var.error_budget_consumption > var.error_budget_threshold * 0.8 ? "WARNING" : "CRITICAL"
  )

  # 格式化后的告警消息模板
  alert_message = format(
    "[%s] 误差预算消耗率: %.2f%%, 状态: %s",
    var.environment,
    var.error_budget_consumption * 100,
    local.compliance_status
  )
}
关键区别： 变量（variable）是模块的输入接口，由调用方赋值；局部值（locals）是模块内部的计算结果，对外部不可见。在供应链台账中，变量定义“是什么”，局部值定义“怎么算”。

3.3 模块化设计：构建可复用的台账组件

模块化是 IaC 复用的核心。将误差预算台账拆分为独立模块，可以实现环境隔离、版本控制和团队协作。

3.3.1 模块结构设计

modules/
├── error-budget-tracker/       # 核心预算追踪模块
│   ├── main.tf                 # 资源定义（监控指标、告警规则）
│   ├── variables.tf            # 输入变量（SLO 目标、时间窗口）
│   ├── outputs.tf              # 输出（消耗率、剩余预算）
│   └── locals.tf               # 局部计算
├── notification-router/        # 通知路由模块
│   ├── main.tf                 # 通知通道资源
│   ├── variables.tf            # 端点配置
│   └── outputs.tf              # 路由状态
└── dashboard-exporter/         # 台账导出模块
    ├── main.tf                 # 导出任务与存储
    ├── variables.tf            # 导出格式、目标路径
    └── outputs.tf              # 导出文件 URL

3.3.2 模块调用示例

# 根模块调用 error-budget-tracker
module "error_budget_tracker" {
  source = "./modules/error-budget-tracker"

  environment          = var.environment
  slo_target           = 0.999
  evaluation_window    = "30d"
  error_budget_threshold = var.error_budget_threshold

  # 传递局部值作为标签
  tags = local.common_tags
}

# 调用通知路由模块，依赖追踪模块的输出
module "notification_router" {
  source = "./modules/notification-router"

  alert_message     = local.alert_message
  compliance_status = module.error_budget_tracker.compliance_status
  endpoints         = var.notification_endpoints
}
版本锁定： 在供应链安全场景中，必须为模块指定精确版本（如 version = "1.2.0"），避免因模块更新引入非预期变更。使用 terraform lock 或 .terraform.lock.hcl 锁定依赖版本。

3.4 for_each 与 count 的高级用法

count 和 for_each 是 Terraform 中实现资源批量管理的两种元参数。在误差预算台账中，它们用于动态创建多个告警规则、多环境部署或批量导出任务。

3.4.1 count：基于索引的批量创建

count 适用于创建一组完全相同的资源实例，例如为多个微服务创建相同的预算告警规则。

# 为 3 个微服务创建相同的误差预算告警
variable "service_names" {
  type    = list(string)
  default = ["api-gateway", "user-service", "payment-service"]
}

resource "monitoring_alert" "error_budget" {
  count = length(var.service_names)

  alert_name = "error-budget-${var.service_names[count.index]}"
  metric     = "error_budget_consumption"
  threshold  = var.error_budget_threshold
  severity   = "critical"
  tags = merge(local.common_tags, {
    Service = var.service_names[count.index]
  })
}

3.4.2 for_each：基于 Map/Set 的灵活批量创建

for_each 适用于每个资源实例具有不同配置的场景，例如为不同 SLO 等级创建差异化的告警规则。

# 为不同 SLO 等级创建差异化的告警规则
variable "slo_tiers" {
  type = map(object({
    slo_target           = number
    evaluation_window    = string
    notification_channel = string
  }))
  default = {
    "gold" = {
      slo_target           = 0.999
      evaluation_window    = "7d"
      notification_channel = "pagerduty"
    }
    "silver" = {
      slo_target           = 0.99
      evaluation_window    = "30d"
      notification_channel = "slack"
    }
    "bronze" = {
      slo_target           = 0.95
      evaluation_window    = "90d"
      notification_channel = "email"
    }
  }
}

resource "monitoring_alert" "tiered_budget" {
  for_each = var.slo_tiers

  alert_name = "error-budget-${each.key}"
  metric     = "error_budget_consumption"
  threshold  = 1 - each.value.slo_target
  window     = each.value.evaluation_window
  channel    = each.value.notification_channel
  tags = merge(local.common_tags, {
    Tier = each.key
  })
}

3.4.3 count vs for_each 对比

特性 count for_each
输入类型 整数或 length(list) map 或 set(string)
资源标识 数字索引 [0], [1]... 键名 ["gold"], ["silver"]...
删除中间元素影响 会导致后续资源重新创建（索引漂移） 仅影响被删除的键，其他资源不变
适用场景 同质化资源列表 差异化配置、Map 驱动的资源
供应链台账推荐 多环境部署（环境列表） 多 SLO 等级、多通知渠道
高级技巧： 在 for_each 中使用 toset() 或 { for k, v in var.map : k => v } 确保输入是 map 类型。对于需要从 list 转换的场景，使用 { for idx, name in var.list : name => idx } 生成 map。

3.5 综合示例：模块化 + for_each 实现多环境台账部署

以下 SVG 图展示了如何将变量、局部值、模块和 for_each 组合，实现多环境误差预算台账的自动化部署。

多环境误差预算台账部署架构（模块化 + for_each） 变量输入 environment, slo_tiers 局部值计算 common_tags, compliance for_each 迭代 each.key / each.value 模块: error-budget-tracker 环境: dev SLO: 0.999 (gold) 窗口: 7d 模块: error-budget-tracker 环境: staging SLO: 0.99 (silver) 窗口: 30d 模块: error-budget-tracker 环境: prod SLO: 0.95 (bronze) 窗口: 90d 输出聚合：budget_consumption_rate, compliance_status, dashboard_url 说明： 1. 变量定义环境与 SLO 等级，局部值计算统一标签和合规状态。 2. for_each 遍历 slo_tiers map，为每个等级创建独立的模块实例。 3. 输出聚合所有环境的台账指标，供 CI/CD 或仪表盘消费。

3.6 供应链安全视角下的进阶用法

在误差预算台账的 IaC 实践中，以下安全策略必须与 HCL 进阶特性结合：

  • 变量敏感标记： 所有 、签名证书等敏感数据必须设置 sensitive = true，并配合 terraform.tfvars 文件加密存储。
  • 模块版本锁定： 使用 version 约束和 .terraform.lock.hcl 锁定模块版本，防止供应链投毒攻击。
  • for_each 的键值校验： 在 for_each 的 map 中使用 validation 块确保键名符合命名规范，避免注入恶意资源名称。
  • 输出最小化原则： 只暴露必要的台账指标，避免将内部变量或敏感计算逻辑通过 output 泄露。
生产级建议： 在 CI/CD 管道中，使用 terraform plan -out=tfplan 生成计划文件，再通过 terraform show -json tfplan 审计所有变量注入和模块调用是否符合供应链安全策略。
← 上一章 📖 返回目录 下一章 →