如何在Terraform子模块文件中直接使用根模块本地变量？

核心结论 #

Terraform不支持子模块直接访问根模块定义的本地变量（local.*）。这是由Terraform的模块化设计原则决定的：模块是隔离的单元，只能通过显式定义的输入变量（variable）接收外部传入的值，以此保证模块的独立性、可复用性和清晰的依赖关系。

为什么不能直接引用？ #

如果子模块可以直接读取根模块的本地变量，会导致模块与根模块强耦合——一旦根模块的变量名或结构变化，所有依赖它的子模块都会失效，而且这样的模块无法在其他项目或环境中独立复用，完全违背了模块化的初衷。

推荐的最佳实践 #

1. 保持显式输入变量传递（最规范方案）

你当前的方案是Terraform官方推荐的标准做法，只需做一些细节优化提升可维护性：

• 统一子模块的输入变量名，比如都叫common_param，避免命名混乱
• 给变量添加类型、描述和可选默认值，增强可读性和健壮性

示例优化后的代码：

# 根目录locals.tf
locals {
  common_variable = "myValue"
}

# 根目录main.tf
module "instance_module_1" {
  source = "./module1"
  common_param = local.common_variable
}

module "instance_module_2" {
  source = "./module2"
  common_param = local.common_variable
}

# module1/module1_main.tf
variable "common_param" {
  type        = string
  description = "由根模块传递的通用配置参数"
  # 可选：设置默认值，避免必须传递
  default     = "defaultValue"
}

resource "some_resource" "some_resource_name" {
  # 必要参数...
  some_specific_parameter = var.common_param
}

# module2/module2_main.tf
variable "common_param" {
  type        = string
  description = "由根模块传递的通用配置参数"
  default     = "defaultValue"
}

resource "some_resource" "some_resource_name" {
  # 必要参数...
  some_specific_parameter = var.common_param
}

2. 其他备选方案（仅特定场景适用）

• 使用模块输出传递：如果通用参数是根模块中某个资源的属性值，可以将其作为根模块的输出，再传递给子模块，但本质还是通过输入变量接收，只是数据源不同。
• 使用环境变量（不推荐）：可以通过TF_VAR_common_variable环境变量传递值，子模块仍需定义对应的variable接收，但这种方式缺乏显式传递的透明度，不利于团队协作和维护。

总结 #

显式通过输入变量传递值是Terraform模块化的核心最佳实践，虽然需要在子模块中定义变量，但换来了模块的独立性、可复用性和清晰的依赖链路，长期来看能大幅降低维护成本。

内容的提问来源于stack exchange，提问作者Akila Induranga