云原生 OpenTofu 模块输入 怎样处理

OpenTofu 模块输入最容易混淆的地方，是把 module 块里的所有字段都当成了子模块变量。实际边界很明确：source、version、for_each、count、providers 和 depends_on 是 OpenTofu 识别的元参数；只有子模块声明过的 variable，才能由父模块按同名参数传入。

官方地址：https://opentofu.org/docs/language/values/variables/

先分清模块元参数和输入变量

子模块像一个有参数的函数：variable 是参数声明，模块内部用 var.名称 读取；父模块通过 module 块调用它。下面的最小配方把两类字段放在一起，正好能看出区别。

module "web" {
  source   = "./modules/web" # 指向子模块位置，不是业务输入
  version  = "1.2.0"         # 注册表模块的版本元参数
  for_each = var.regions      # 用集合决定模块实例数量

  app_name = each.key        # 子模块声明的 variable 才能这样传入
  replicas = each.value
}

如果子模块没有声明 app_name 或 replicas，计划阶段会提示未声明的模块参数。反过来，子模块的资源属性也不会因为放进了模块目录就自动暴露给父模块，必须通过 output 导出。

用类型和默认值建立输入契约

可复用模块不要只写一个裸变量。至少给外部调用者说明类型和用途；对必须存在的值，去掉默认值；对对象配置，则把结构固定下来，避免调用者传入一组含义不明的字符串。

variable "service" {
  type = object({
    name     = string
    replicas = number
    image    = string
  })
  description = "服务名称、副本数和镜像地址"
  nullable    = false # 整个对象不能为 null

  validation {
    condition     = var.service.replicas >= 1
    error_message = "replicas 必须大于或等于 1"
  }
}

default 会让输入变成可选项，但默认值必须是字面量，不能引用另一个资源。nullable 默认是 true；若调用者显式传入 null，通常会覆盖默认值。需要禁止这种语义时，将它设为 false，再根据业务决定是否提供默认对象。

按来源优先级排查传值异常

根模块的变量可以来自 TF_VAR_变量名、terraform.tfvars、自动加载的 *.auto.tfvars，也可以来自 -var-file 和 -var。后出现的来源覆盖先出现的来源；同一个来源内部不能重复定义同名变量。排查时先把这些来源列成清单，不要直接改模块代码。

# 先用文件承载一组可复现的测试输入
tofu plan -var-file="staging.tfvars" # 明确指定环境文件

# 临时覆盖一个值；多个 -var 按命令行顺序处理
tofu plan -var='service={name="api",replicas=2,image="app:v3"}'

修改 module 块中的 source、模块版本或嵌套模块后，要重新运行 tofu init，让 OpenTofu 更新已安装的模块。只改普通输入通常进入 tofu plan 就能看到差异；如果仍然看不到预期值，再检查是否在错误的根模块目录执行命令。

相关问题

module 块里能不能直接写任意字段？

不能。除元参数外，字段必须对应子模块已声明的输入变量，否则会被视为未声明的模块参数。

为什么传入 null 后默认值消失了？

变量默认值用于“没有赋值”的场景；当变量允许 null 时，显式的 null 是一次真实赋值。需要拒绝它时设置 nullable = false。

子模块里的变量能从环境变量直接读取吗？

环境变量入口主要用于根模块变量。子模块输入应由调用它的父模块在 module 块中显式传递，这样模块契约和复用边界更清楚。