All Products
Search

This Product

    Terraform:Module meta-arguments

    Document Center

    Terraform:Module meta-arguments

    Last Updated:Apr 21, 2025

    This topic describes meta-arguments of modules.

    This previous topic describes the source argument. This topic describes meta-arguments of modules and how they change the way modules behave.

    Overview

    Meta-arguments of a Terraform module are a special set of configuration options. They do not directly define resource attributes, but control the behavior and usage of the module. These meta-arguments provide the module with additional flexibility and functionality, enabling the module to adapt to different deployment scenarios and architectural requirements. You can use meta-arguments to create multiple module instances, control the order in which resources are deployed, manage provider configurations, and customize the lifecycle behavior of modules.

    Terraform modules support a variety of meta-arguments, including providers (which allows specific provider configurations to be passed to child modules), depends_on (which defines explicit dependencies between modules), count (which creates multiple identical module instances), and for_each (which creates different module instances based on mappings or collections). These meta-arguments are particularly important in complex multi-region deployments, conditional resource creation, cross-account resource management, and large-scale infrastructure orchestration.

    Proper use of meta-arguments simplifies cross-region resource deployment, enables conditional creation of resources, ensures proper initialization order of resources, and allows you to manage multiple environments with a single configuration. This topic describes the features, usage, and application scenarios of the providers meta argument. For more information about other meta arguments, see depends_on, count, and for_each.

    providers

    providers allows you to specify which provider configurations from the parent module are available within the child module. This is especially useful when dealing with multi-region or multi-account resources.

    Usage

    # Define the default Alibaba Cloud provider configuration in the root module for the China (Hangzhou) region.
provider "alicloud" {
  region = "cn-hangzhou"
}

# Define another configuration for the China (Beijing) region and use the alias "bj".
provider "alicloud" {
  alias  = "bj"
  region = "cn-beijing"
}

# Use the configuration of the China (Beijing) region when instantiating the child module
module "ecs_cluster" {
  source = "./modules/ecs-cluster"
  providers = {
    alicloud = alicloud.bj
  }
}

    Default behavior: Inherit the default provider

    The providers argument is optional if the child module does not declare any configuration aliases. If you do not use the argument, the child module inherits all default provider configurations from its parent module, which are configurations that do not use alias.

    If providers is specified, this default behavior is canceled and the child module only has access to the provider configuration that you specify.

    Usage and behavior

    The value of providers is a map where:

    • The key is the provider configuration name used within the child module.

    • The value is the provider configuration name from the parent module.

    The key and the value must be unquoted references to provider configurations. For the default configuration, this is the local name of the provider. For the alternative configuration, this is the <PROVIDER>.<ALIAS> reference.

    In the child module, resources are allocated to provider configurations in the following ways:

    1. Terraform selects the default value based on the name of the resource type.

    2. Resources use the provider argument to specify an alternative configuration.

    If the module receives a providers mapping at the time of the call, the provider configuration name used within the module is remapped to refer to the configuration specified in the parent module.

    When to specify providers

    There are two main reasons to use providers:

    1. Use different default provider configurations for child modules: For example, you need to deploy module resources to different regions.

    2. Configure modules that require multiple configurations of the same provider. For example, you want to manage resource interactions between different regions.

    Change the default provider configuration

    Most reusable modules only use the default provider configuration. They can automatically inherit from the caller when providers is omitted.

    However, in a Terraform configuration that uses multiple configurations from the same provider, you may want some child modules to use the default provider configuration, while other modules use alternative configurations. This usually happens when using one configuration to manage resources in multiple different regions of the same cloud provider.

    By using providers (as shown in the preceding example), you can achieve this without editing the child module. Although the code within the child module always refers to the default provider configuration, the actual configuration may be different for each instance.

    For a similar module, see hybrid-cloud-network.

    Modules with alternative provider configurations

    In rare cases, a single reusable module may require multiple configurations from the same provider. For example, a module that configures a connection between two Alibaba Cloud regions may require a source region and a destination region. In this case, the root module might look like this:

    # Define the configuration of the China (Hangzhou) region.
provider "alicloud" {
  alias  = "hangzhou"
  region = "cn-hangzhou"
}

# Define the configuration of the China (China) region.
provider "alicloud" {
  alias  = "beijing"
  region = "cn-beijing"
}

# Map the two provider configurations in the module call.
module "vpc_peering" {
  source    = "./modules/vpc-peering"
  providers = {
    alicloud.source      = alicloud.hangzhou
    alicloud.destination = alicloud.beijing
  }
}

    Non-default provider configurations are never automatically inherited, so any module that works this way will always need providers. The documentation of the module must specify all the provider configuration names that the module requires.

    For a similar module, see cen-cross-region-networking-with-qos.

    Examples

    Cross-region resource management

    # Define the provider configuration for the China (Hangzhou) region.
provider "alicloud" {
  region = "cn-hangzhou"
}

# Define the provider configuration for the China (Shenzhen) region.
provider "alicloud" {
  alias  = "shenzhen"
  region = "cn-shenzhen"
}

# Use the default China (Hangzhou) region to deploy the primary VPC.
module "primary_vpc" {
  source = "alibaba/vpc/alicloud"
  
  vpc_name       = "primary-vpc"
  vpc_cidr       = "10.0.0.0/16"
  # If providers is not specified, the default China (Hangzhou) region is used.
}

# Deploy a disaster recovery VPC in the China (Shenzhen) region.
module "dr_vpc" {
  source = "alibaba/vpc/alicloud"
  
  vpc_name       = "dr-vpc"
  vpc_cidr       = "10.1.0.0/16"
  
  providers = {
    alicloud = alicloud.shenzhen
  }
}

    Cross-region data replication

    When the module needs to manage two regions:

    # Inside the child module (./modules/oss-replication/main.tf)
terraform {
  required_providers {
    alicloud = {
      source  = "aliyun/alicloud"
      # Declare that this module requires two Alibaba Cloud provider configurations.
      configuration_aliases = [ alicloud.source, alicloud.replica ]
    }
  }
}

# Create a source bucket.
resource "alicloud_oss_bucket" "source" {
  provider = alicloud.source
  bucket   = var.source_bucket_name
  # Other configurations.
}

# Create a destination bucket.
resource "alicloud_oss_bucket" "replica" {
  provider = alicloud.replica
  bucket   = var.replica_bucket_name
  # Other configurations.
}

# Configure replication rules.
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
  # Other configurations.
}

    Make a call in the root module:

    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
  }
}

    For a similar module, see cen-cross-region-networking-with-qos.

    In this way, providers allows you to specify which provider configurations are used by child modules, simplifying cross-region or cross-account resource management.