All Products
Search

This Product

    Terraform:source

    Document Center

    Terraform:source

    Last Updated:Apr 11, 2025

    This topic introduces the most important argument in a module block: source.

    The Configure a module block topic describes the syntax of module blocks. This topic describes the most important argument in a module block: source.

    Overview

    In the modularized architecture of Terraform, the source argument is the most important element in a module block. This argument defines the source location of the module code. Proper use of the source argument helps you build a maintainable, reusable, and secure infrastructure. The source argument may point to different types of locations, such as a local path, Git, Terraform Registry, or a remote storage service. Each type has its specific syntax and use scenarios.

    The source argument allows Terraform to obtain, download, and prepare the module code during initialization. The module code is used for the Plan and Apply operations. This is a flexible method to obtain modules, which allows your team to build a module repository and share and standardize module code. In addition, the source argument is typically used together with the versioning argument, such as version in Terraform Registry and ref in Git, to ensure the consistency and reusability of the infrastructure.

    Choosing a proper module source is particularly important for team collaboration, security management, and continuous integration (CI) and continuous delivery (CD). This topic describes the major source types of the source argument and how to use the source argument and argument options. You can fully maximize the capabilities of the Terraform module system to manage Alibaba Cloud resources. For more information, see Module Sources.

    source details

    The source argument informs Terraform the location of the source code of a child module. When Terraform runs the terraform init command to install a module, Terraform uses the source argument to download the source code of the module to a local disk so that other Terraform commands can also use the code.

    Terraform allows you to install modules from various types of sources. Supported source types:

    1. Local paths

    A local path allows you to reuse code within a single source code repository. 

    module "vpc" {
  source = "./vpc"
}

module "ecs" {
  source = "../modules/ecs"
}

    The local path must start with ./ or ../, which indicates a local path instead of a remote path.

    • Characteristics:

      • The local path module is not installed but directly used.

      • When the parent module is upgraded, the source code is automatically updated.

      • We recommend that you do not use the absolute path of a file system to reference a module.

    • Reference child modules: For a local path, you can specify a subdirectory to reference a child module. Sample code:

    module "vpc_subnet" {
  source = "./vpc/modules/subnet"
}

    2. Terraform Registry

    Terraform Registry uses a native method to distribute Terraform modules across configurations. It supports full module versioning. 

    module "ecs" {
  source  = "alibaba/ecs-instance/alicloud"
  version = "1.2.0"
}

    • Address format: <NAMESPACE>/<NAME>/<PROVIDER>.

      • <NAMESPACE>: the module publisher or organization that owns that maintains the module.

    • Main namespaces for Alibaba Cloud modules:

      • alibaba: the main module maintained by Alibaba Cloud.

      • aliyun: the module in the backup Alibaba Cloud namespace.

      • terraform-alicloud-modules: the previous method in which Alibaba Cloud modules are organized.

      • alibabacloud-automation: the module that is maintained by the Alibaba Cloud automation team.

      • For example, alibaba in alibaba/ecs-instance/alicloud indicates that the module is maintained by Alibaba Cloud.

    • <NAME>: the name of the module that indicates that feature or purpose of the module.

      • The name typically describes the resource type created and managed by the module.

      • For example, ecs-instance in alibaba/ecs-instance/alicloud indicates that the module is used to create and manage Elastic Compute Service (ECS) instances.

      • Other common names include vpc, slb, rds, and security-group. They represent Alibaba Cloud resources.

    • <PROVIDER>: the Terraform provider to which the module is applicable.

      • Set the value to alicloud for Alibaba Cloud modules.

      • The provider identifies the cloud platform with which the module is integrated.

      • alicloud in alibaba/ecs-instance/alicloud indicates that the module is provided by Alibaba Cloud.

    • Examples:

      • alibaba/vpc/alicloud: the module that is used to create Alibaba Cloud virtual private clouds (VPCs).

      • terraform-alicloud-modules/security-group/alicloud: the module that is used to create Alibaba Cloud security groups.

      • alibabacloud-automation/multiple-vpc-networks-peering/alicloud: the module that is used to create high-efficiency, high-security, and high-availability architectures that deploy multiple VPCs within the same region.

      • For more information about Alibaba Cloud modules, visit Terraform Registry.

    • Reference child modules: In most cases, Registry modules split features into child modules. You can use double forward slashes (//) to reference a child module. Sample code:

    module "nat_gateway" {
  source  = "alibaba/vpc/alicloud//modules/nat-gateway"
  version = "1.10.0"
}

    3. GitHub

    Terraform automatically identifies the GitHub URL and interprets it as a Git repository source. 

    # The HTTPS method.
module "vpc" {
  source = "github.com/alibabacloud-automation/terraform-alicloud-ram"
}

# The SSH method.
module "vpc" {
  source = "git@github.com:alibabacloud-automation/terraform-alicloud-ram.git"
}

    In fact, the GitHub solutions are the aliases of common Git repository addresses. Therefore, they use the same method to obtain credentials and allow you to use the ref parameter to specify a version.

    Reference child modules:

    # Reference a child module in a GitHub repository.
module "vpc_subnet" {
  source = "github.com/alibabacloud-automation/terraform-alicloud-ram//modules/ram-user"
}

# Reference a child module of a specific version by using SSH.
module "vpc_subnet" {
  source = "git@github.com:alibabacloud-automation/terraform-alicloud-ram.git//modules/ram-user?ref=v2.1.0"
}

    4. Common Git repositories

    To reference a Git repository, add the special prefix git:: to the address. Sample code:

    # The HTTPS method.
module "vpc" {
  source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git"
}

# The SSH method.
module "vpc" {
  source = "git::ssh://git@github.com/alibabacloud-automation/terraform-alicloud-vpc.git"
}

    Reference child modules:

    # Reference a child module 
module "vpc_subnet" {
  source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-ram.git//modules/ram-user?ref=v2.1.0"
}

# Reference a child module in a private Git repository.
module "security_component" {
  source = "git::ssh://git@example.com/company/terraform-modules.git//security/waf?ref=v1.0.0"
}

    Specify a version

    By default, Terraform clones and uses the default branch in the selected repository. You can configure the ref parameter to specify a branch, a tag, or a hash value. Sample code:

    # Specify a tag.
module "vpc" {
  source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git?ref=v1.11.0"
}

# Specify a commit.
module "vpc" {
  source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"
}

    Shallow clone

    If the repository is large, you can perform a shallow clone to reduce the time required for retrieving data from a remote repository. Sample code:

    module "vpc" {
  source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git?depth=1&ref=v1.11.0"
}

    5. HTTP URLs

    If you use an HTTP or HTTPS URL, Terraform sends GET requests to the URL, which then returns another source address. Sample code:

    module "vpc" {
  source = "https://example.com/modules/vpc"
}

    If Terraform detects that the URL extension is related to the format of the archived file, Terraform directly references the content of the archived file as the module source code. Sample code:

    module "vpc" {
  source = "https://example.com/vpc-module.zip"
}

    Supported extensions:

    • zip

    • bz2, tar.bz2, tar.tbz2, tbz2

    • gz, tar.gz, tgz

    • xz, tar.xz, txz

    Reference child modules:

    # Reference a child module from an archived ZIP file.
module "vpc_subnet" {
  source = "https://example.com/vpc-module.zip//modules/subnet"
}

    Best practices

    1. Select an appropriate source type:

      • We recommend that you use local file paths to reference business-critical modules.

      • If you need to configure a module that is shared among multiple configurations, we recommend that you use Terraform Registry.

    2. Versioning:

      • Specify a module version in the production environment.

      • We recommend that you use semantic versioning to specify an appropriate version scope.

    3. Suggestions on Alibaba Cloud modules:

      • We recommend that you preferentially use Alibaba Cloud modules.

      • Make sure that the module is compatible with the desired region.

      • Pay attention to the resource limits in each region.

    4. Security:

      • Use HTTPS or SSH to obtain modules.

      • Configure valid credentials for private repositories.

      • Update the modules on a regular basis to prevent security risks.

    Examples

    Alibaba Cloud modules

    provider "alicloud" {
 region = "cn-hangzhou"
}
module "ecs" {
  source  = "alibaba/ecs-instance/alicloud"
  version = "2.5.0"
  
  instance_type = "ecs.g6.large"
  # Other configurations.
}

    Internal module repositories of a company

    module "security_baseline" {
  source = "git::ssh://git@example.com/company/security-baseline.git?ref=v1.0.0"
  
  environment = "production"
  # Other configurations.
}

    Multi-environment configurations

    # The development environment.
module "vpc_dev" {
  source  = "alibaba/vpc/alicloud"
  version = "~> 1.10.0"  # The allowed patch versions.
  
  environment = "dev"
  # Other configurations.
}

# The production environment.
module "vpc_prod" {
  source  = "alibaba/vpc/alicloud"
  version = "1.10.0"  # Specify a specific version.
  
  environment = "prod"
  # Other configurations.
}

    You can flexibly configure the source argument to build a secure and maintainable modularized Terraform architecture.