AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 Terraform 基础知识 代码编写 Module Module Source详解

Module Source详解

更新时间：
我的收藏

本节将详细介绍 Module 块中最重要的参数 source。

在上一节中，我们了解了 Module 块的基本语法。本节将详细介绍 Module 块中最重要的参数：source。

概述

在 Terraform 的模块化架构中，source 参数是 Module 块中最核心的元素，它定义了模块代码的来源位置。理解和正确使用 source 参数对于构建可维护、可重用且安全的基础设施代码至关重要。source 参数可以指向多种不同类型的位置，包括本地路径、Git、Registry 或各种远程存储服务，每种方式都有其特定的语法和用例。

通过 source 参数，Terraform 能够在初始化过程中获取、下载和准备模块代码，使其可用于后续的 Plan 和 Apply 操作。这种灵活的模块获取机制使团队能够建立模块库，实现代码共享和标准化。此外，source 参数通常与版本控制参数（如 Registry中的 version，Git 中的 ref 等）结合使用，确保基础设施部署的一致性和可重复性。

选择合适的模块源对于团队协作、安全管理和持续集成/持续部署（CI/CD）流程尤为重要。本文档将详细介绍 source 参数的主要源类型以及对应的使用方法和参数选项，帮助您充分利用 Terraform 模块系统的强大功能来管理阿里云资源。更多的源类型可详见 Module Sources。

source 详解

source 参数告诉 Terraform 在哪里查找子模块的源代码。Terraform 在执行 terraform init 命令的模块安装步骤期间，会使用此参数下载源代码到本地磁盘，以便其他 Terraform 命令可以使用它。

Terraform 支持从多种不同的源类型安装 Module。以下是支持的主要源类型：

1. 本地路径 (Local Paths)

本地路径引用允许在单个源代码仓库内部重用代码。

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

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

本地路径必须以 ./ 或 ../ 开头，以表明是本地路径，而不是远端地址。

  • 特点：

    • 本地路径模块不会被"安装"，而是直接使用

    • 父模块升级时，源代码会自动更新

    • 不建议使用绝对文件系统路径引用模块

  • 引用子模块： 对于本地路径，可以直接指定子目录路径来引用子模块：

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

2. Terraform Registry

Registry 是跨多个配置分发 Terraform 模块的原生方式，它支持完整的模块版本控制。

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

  • 地址格式：<NAMESPACE>/<NAME>/<PROVIDER>

    • <NAMESPACE>：表示模块发布者或组织。它定义了谁拥有和维护该模块。

  • 对于阿里云的模块，主要命名空间包括：

    • alibaba：阿里云官方维护的主要模块

    • aliyun：阿里云备用命名空间下的模块

    • terraform-alicloud-modules：早期阿里云模块组织方式

    • alibabacloud-automation：阿里云自动化团队维护的模块

    • 例如，alibaba/ecs-instance/alicloud 中的 alibaba 表示该模块由阿里云官方维护

  • <NAME>：表示模块的名称，反映模块的功能或用途。

    • 名称通常描述该模块创建和管理的资源类型

    • 例如，alibaba/ecs-instance/alicloud 中的 ecs-instance 表示该模块用于创建和管理阿里云 ECS 实例

    • 其他常见名称还有 vpc、slb、rds、security-group 等，反映了相应的阿里云资源

  • <PROVIDER>：表示该模块适用的 Terraform 提供商。

    • 对于阿里云的模块，此值固定为 alicloud

    • 提供商标识了该模块与哪个云平台集成

    • 例如，alibaba/ecs-instance/alicloud 中的 alicloud 表示该模块使用阿里云提供商

  • 完整示例：

    • alibaba/vpc/alicloud：创建阿里云 VPC 的官方模块

    • terraform-alicloud-modules/security-group/alicloud：创建阿里云安全组的模块

    • alibabacloud-automation/multiple-vpc-networks-peering/alicloud: 构建高效、安全且高可用的同区域多VPC网络架构

    • 更多阿里云官方模块可在 Terraform Registry找到。

  • 引用子模块： Registry模块通常会将相关功能拆分为子模块，可以通过双斜杠语法 // 引用：

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

3. GitHub

Terraform 会自动识别 GitHub URL 并将其解释为 Git 仓库源。

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

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

这些 GitHub 方案实际上是通用 Git 仓库地址方案的别名，因此它们以相同的方式获取凭据，并支持 ref 参数来选择特定版本。

引用子模块：

# 引用GitHub仓库中的子模块
module "vpc_subnet" {
  source = "github.com/alibabacloud-automation/terraform-alicloud-ram//modules/ram-user"
}

# 通过SSH方式引用特定版本的子模块
module "vpc_subnet" {
  source = "git@github.com:alibabacloud-automation/terraform-alicloud-ram.git//modules/ram-user?ref=v2.1.0"
}

4. 通用 Git 仓库

可以通过在地址前加上特殊前缀 git:: 来使用任意 Git 仓库：

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

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

引用子模块：

# 引用Git仓库中的子模块并选择特定版本
module "vpc_subnet" {
  source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-ram.git//modules/ram-user?ref=v2.1.0"
}

# 引用私有Git仓库中的子模块
module "security_component" {
  source = "git::ssh://git@example.com/company/terraform-modules.git//security/waf?ref=v1.0.0"
}

选择特定版本

默认情况下，Terraform 会克隆并使用所选仓库中的默认分支。可以使用 ref 参数来指定分支、标签或提交哈希：

# 选择特定标签
module "vpc" {
  source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git?ref=v1.11.0"
}

# 选择特定提交
module "vpc" {
  source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"
}

浅克隆

对于较大的存储库，您可能希望仅进行浅克隆以减少检索远程存储库所需的时间：

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

5. HTTP URLs

当使用 HTTP 或 HTTPS URL 时，Terraform 会向给定URL发送 GET 请求，该 URL 可以返回另一个源地址：

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

如果 Terraform 检测到 URL 具有与归档文件格式相关的扩展名，它将直接使用引用的归档内容作为模块源代码：

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

支持的扩展名包括：

  • zip

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

  • gz, tar.gz, tgz

  • xz, tar.xz, txz

引用子模块：

# 从zip归档文件中引用子模块
module "vpc_subnet" {
  source = "https://example.com/vpc-module.zip//modules/subnet"
}

最佳实践

  1. 选择合适的源类型：

    • 对于密切相关的模块，推荐使用本地文件路径

    • 对于需要在多个配置间共享的模块，推荐使用 Terraform Registry

  2. 版本控制：

    • 始终在生产环境中指定模块版本

    • 使用语义化版本控制选择适当的版本约束

  3. 阿里云特定建议：

    • 优先使用阿里云官方模块

    • 确保模块与目标区域兼容

    • 注意区域特定的资源限制

  4. 安全性考虑：

    • 使用 HTTPS 或 SSH 协议获取模块

    • 对于私有仓库，正确配置凭据

    • 定期更新模块版本以获取安全修复

实际应用示例

阿里云官方模块

provider "alicloud" {
 region = "cn-hangzhou"
}
module "ecs" {
  source  = "alibaba/ecs-instance/alicloud"
  version = "2.5.0"
  
  instance_type = "ecs.g6.large"
  # ... 其他配置
}

企业内部模块仓库

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

多环境配置

# 开发环境
module "vpc_dev" {
  source  = "alibaba/vpc/alicloud"
  version = "~> 1.10.0"  # 允许补丁版本更新
  
  environment = "dev"
  # ... 其他配置
}

# 生产环境
module "vpc_prod" {
  source  = "alibaba/vpc/alicloud"
  version = "1.10.0"  # 锁定特定版本
  
  environment = "prod"
  # ... 其他配置
}

通过灵活使用不同的 source 参数类型，您可以构建既安全又可维护的 Terraform 模块化架构。

上一篇：Module块配置下一篇：Module元参数详解