Module元参数详解_Terraform(Terraform)-阿里云帮助中心

本节将详细介绍 Module 块的元参数（Meta-arguments）

在上一节中，我们了解了 Module 块的 source 参数。本节将详细介绍 Module 块的元参数（Meta-arguments），这些元参数可以改变模块的行为方式。

概述

Terraform 模块（Module）的元参数（Meta-arguments）是一组特殊的配置选项，它们不直接定义资源属性，而是控制模块的行为和使用方式。这些元参数为模块提供了额外的灵活性和功能，使模块能够适应不同的部署场景和架构需求。通过元参数，您可以创建多个模块实例、控制资源部署顺序、管理提供商配置，以及自定义模块的生命周期行为。

Terraform 模块支持多种元参数，包括 providers（允许将特定提供商配置传递给子模块）、depends_on（定义模块间的显式依赖关系）、count（创建多个相同模块实例）和 for_each（基于映射或集合创建不同的模块实例）。这些元参数在复杂的多区域部署、条件性资源创建、跨账户资源管理以及大规模基础设施编排中尤为重要。

正确使用模块元参数可以简化跨区域资源部署、实现资源的条件性创建、确保资源的正确初始化顺序，以及使用单一配置管理多个环境。本文档将详细解析元参数 providers 的功能、使用方法和实际应用场景，其他元参数详见 depends_on，count 和 for_each。

providers 元参数

providers 元参数允许您指定哪些来自父模块的提供商配置可在子模块内使用。这在处理多区域或多账户资源时特别有用。

基本用法

# 在根模块中定义默认的阿里云提供商配置用于华东1（杭州）区域
provider "alicloud" {
  region = "cn-hangzhou"
}

# 另外定义一个用于华北2（北京）区域的配置，使用别名 "bj"
provider "alicloud" {
  alias  = "bj"
  region = "cn-beijing"
}

# 实例化子模块时使用北京区域的配置
module "ecs_cluster" {
  source = "./modules/ecs-cluster"
  providers = {
    alicloud = alicloud.bj
  }
}

默认行为：继承默认提供商

如果子模块没有声明任何配置别名，则 providers 参数是可选的。如果省略它，子模块将从其父模块继承所有默认提供商配置（即没有使用 alias 参数的配置）。

如果指定了 providers 参数，则会取消这种默认行为，子模块将只能访问您指定的提供商配置。

用法和行为

providers 的值是一个映射，其中：

键是子模块内使用的提供商配置名称。
值是来自父模块的提供商配置名称。

键和值都应该是对提供商配置的未加引号的引用。对于默认配置，这是提供商的本地名称；对于替代配置，这是 <PROVIDER>.<ALIAS> 引用。

在子模块内部，资源按正常方式分配给提供商配置：

要么 Terraform 根据资源类型的名称选择默认值
要么资源使用 provider 参数指定替代配置

如果模块在调用时接收到 providers 映射，则模块内使用的提供商配置名称会被重新映射，以引用父模块中指定的配置。

何时指定 providers

使用 providers 参数的两个主要原因：

为子模块使用不同的默认提供商配置：例如，使模块资源部署到不同的区域。
配置需要同一提供商的多个配置的模块：例如，管理不同区域之间的资源交互。

更改默认提供商配置

大多数可重用模块只使用默认提供商配置，即省略 providers 时，它们可以自动从调用者继承。

然而，在使用同一提供商的多个配置的 Terraform 配置中，您可能希望某些子模块使用默认提供商配置，而其他模块使用替代配置（这通常发生在使用一个配置管理同一云提供商的多个不同区域中的资源时）。

通过使用 providers 参数（如上面的代码示例所示），您可以在不需要编辑子模块的情况下实现这一点。尽管子模块内的代码始终引用默认提供商配置，但每个实例的实际配置可能不同。

类似的 Module 可参考 hybrid-cloud-network。

具有替代提供商配置的模块

在极少数情况下，单个可重用模块可能需要同一提供商的多个配置。例如，一个配置两个阿里云区域之间连接的模块可能需要源区域和目标区域。在这种情况下，根模块可能如下所示：

# 定义杭州区域配置
provider "alicloud" {
  alias  = "hangzhou"
  region = "cn-hangzhou"
}

# 定义北京区域配置
provider "alicloud" {
  alias  = "beijing"
  region = "cn-beijing"
}

# 在模块调用中映射这两个提供商配置
module "vpc_peering" {
  source    = "./modules/vpc-peering"
  providers = {
    alicloud.source      = alicloud.hangzhou
    alicloud.destination = alicloud.beijing
  }
}

非默认提供商配置永远不会自动继承，因此任何这样工作的模块总是需要 providers 参数。模块的文档应该指定它需要的所有提供商配置名称。

类似的 Module 可参考 cen-cross-region-networking-with-qos。

使用示例

跨区域资源管理

# 定义华东1（杭州）区域的提供商配置
provider "alicloud" {
  region = "cn-hangzhou"
}

# 定义华南1（深圳）区域的提供商配置
provider "alicloud" {
  alias  = "shenzhen"
  region = "cn-shenzhen"
}

# 使用默认区域（杭州）部署主VPC
module "primary_vpc" {
  source = "alibaba/vpc/alicloud"
  
  vpc_name       = "primary-vpc"
  vpc_cidr       = "10.0.0.0/16"
  # 未指定providers，使用默认的杭州区域
}

# 使用深圳区域部署灾备VPC
module "dr_vpc" {
  source = "alibaba/vpc/alicloud"
  
  vpc_name       = "dr-vpc"
  vpc_cidr       = "10.1.0.0/16"
  
  providers = {
    alicloud = alicloud.shenzhen
  }
}

跨区域数据复制模块

当模块内部需要同时操作两个区域时：

# 在子模块内部 (./modules/oss-replication/main.tf)
terraform {
  required_providers {
    alicloud = {
      source  = "aliyun/alicloud"
      # 声明此模块需要两个alicloud提供商配置
      configuration_aliases = [ alicloud.source, alicloud.replica ]
    }
  }
}

# 创建源存储桶
resource "alicloud_oss_bucket" "source" {
  provider = alicloud.source
  bucket   = var.source_bucket_name
  # 其他配置...
}

# 创建复制目标存储桶
resource "alicloud_oss_bucket" "replica" {
  provider = alicloud.replica
  bucket   = var.replica_bucket_name
  # 其他配置...
}

# 配置复制规则
resource "alicloud_oss_bucket_replication" "this" {
  provider        = alicloud.source
  bucket          = alicloud_oss_bucket.source.bucket
  target_bucket   = alicloud_oss_bucket.replica.bucket
  target_region   = var.replica_region
  # 其他配置...
}

然后在根模块中调用：

provider "alicloud" {
  alias  = "hangzhou"
  region = "cn-hangzhou"
}

provider "alicloud" {
  alias  = "beijing"
  region = "cn-beijing"
}

module "oss_replication" {
  source = "./modules/oss-replication"
  
  source_bucket_name  = "source-data-bucket"
  replica_bucket_name = "replica-data-bucket"
  replica_region      = "cn-beijing"
  
  providers = {
    alicloud.source  = alicloud.hangzhou
    alicloud.replica = alicloud.beijing
  }
}

类似的 Module 可参考 cen-cross-region-networking-with-qos。

通过这种方式，providers 元参数允许您灵活地控制子模块使用哪些提供商配置，使得跨区域或跨账户的资源管理变得更加简单和清晰。