模块源

source 参数在 module 块中告诉 OpenTofu 在哪里可以找到所需子模块的源代码。

OpenTofu 在 tofu init 的模块安装步骤中使用它，将源代码下载到本地磁盘上的目录，以便其他 OpenTofu 命令可以使用它。

模块安装程序支持从多种不同的源类型进行安装。

本地路径
模块注册表
GitHub
Bitbucket
通用 Git、Mercurial 存储库
HTTP URL
S3 存储桶
GCS 存储桶
软件包子目录中的模块

以下各节将描述每个内容。模块源地址使用类似 URL 的语法，但扩展为支持明确的源选择和附加功能。

建议对主要用于提取重复代码元素的密切相关的模块使用本地文件路径，而对旨在由多个调用配置共享的模块使用原生 OpenTofu 模块注册表。我们支持其他源，以便您能够使用现有基础设施在内部分发 OpenTofu 模块。

许多源类型将使用运行 OpenTofu 时可用的“环境”凭据，例如来自环境变量或主目录中的凭据文件。这将在以下各节中详细介绍。

建议将每个旨在可重用的模块放在其自身存储库或存档文件的根目录中，但也可以从子目录引用模块。

本地路径

本地路径引用允许在单个源存储库中提取配置的一部分。

代码块
module "consul" {
  source = "./consul"
}

本地路径必须以 ./ 或 ../ 开头，以指示本地路径的意图，以区别于模块注册表地址。

本地路径很特殊，因为它们不以与其他源相同的方式“安装”：这些文件已经存在于本地磁盘上（可能是由于安装了父模块），因此可以直接使用。如果父模块升级，它们的源代码将自动更新。

请注意，OpenTofu 不认为绝对文件系统路径（以斜杠、驱动器号或类似符号开头）是本地路径。相反，OpenTofu 将以类似于远程模块的方式处理它，并将其复制到本地模块缓存中。绝对路径是软件包子目录中的模块中所述的“软件包”。我们不建议使用绝对文件系统路径引用模块，因为它往往会将您的配置与特定计算机的文件系统布局耦合。

模块注册表

模块注册表是将模块分发到多个配置以供使用的原生方式，使用 OpenTofu 特定协议，该协议完全支持模块版本控制。

您可以使用公共 OpenTofu 注册表，该注册表是使用此协议公开共享的模块的索引。此公共注册表是开始使用 OpenTofu 和查找社区中其他人创建的模块的最简单方法。

您还可以使用私有注册表，无论是通过 TACOS（TF 自动化和协作软件），还是通过运行实现模块注册表协议的自定义服务。

公共注册表上的模块可以使用 <NAMESPACE>/<NAME>/<PROVIDER> 形式的注册表源地址引用，注册表站点上每个模块的信息页面都包含要使用的确切地址。

代码块
module "consul" {
  source = "hashicorp/consul/aws"
  version = "0.1.0"
}

上面的示例将使用来自公共注册表的 AWS 的 Consul 模块。

对于托管在其他注册表中的模块，请在源地址前面添加 <HOSTNAME>/ 部分，提供私有注册表的 hostname

代码块
module "consul" {
  source = "app.terraform.io/example-corp/k8s-cluster/azurerm"
  version = "1.1.0"
}

注册表模块支持版本控制。您可以提供特定版本，如上面的示例所示，或者使用灵活的版本约束。

您可以在模块注册表文档中了解更多关于注册表的信息。

要从私有注册表访问模块，您可能需要配置一个访问令牌在 CLI 配置中。使用与模块源字符串中使用的相同的主机名。对于 TACOS（TF 自动化和协作软件）中的私有注册表，请使用与 API 或命令行客户端相同的身份验证令牌。

GitHub

OpenTofu 将识别没有前缀的 github.com URL 并将其自动解释为 Git 存储库源。

代码块
module "consul" {
  source = "github.com/hashicorp/example"
}

上述地址方案将通过 HTTPS 克隆。要通过 SSH 克隆，请使用以下格式

代码块
module "consul" {
  source = "[email protected]:hashicorp/example.git"
}

这些 GitHub 方案被视为通用 Git 存储库地址方案的便捷别名，因此它们以相同的方式获取凭据并支持 ref 参数用于选择特定修订版。您需要特别配置凭据才能访问私有存储库。

Bitbucket

OpenTofu 将识别没有前缀的 bitbucket.org URL 并将其自动解释为 BitBucket 存储库。

代码块
module "consul" {
  source = "bitbucket.org/example-corp/tofu-consul-aws"
}

此简写仅适用于公共存储库，因为 OpenTofu 必须访问 BitBucket API 才能了解给定存储库是否使用 Git 或 Mercurial。

OpenTofu 根据存储库类型将结果视为 Git 源或 Mercurial 源。请参阅有关每种版本控制类型的部分，了解如何为私有存储库配置凭据以及如何指定要安装的特定修订版。

通用 Git 存储库

可以通过在地址前加上特殊的 git:: 前缀来使用任意 Git 存储库。在此前缀之后，可以指定任何有效的 Git URL 来选择 Git 支持的协议之一。

例如，要使用 HTTPS 或 SSH

代码块
module "vpc" {
  source = "git::https://example.com/vpc.git"
}

module "storage" {
  source = "git::ssh://[email protected]/storage.git"
}

OpenTofu 通过运行 git clone 从 Git 存储库安装模块，因此它将尊重您系统上设置的任何本地 Git 配置，包括凭据。要访问非公开 Git 存储库，请使用该存储库的合适凭据配置 Git。

如果您使用 SSH 协议，则任何已配置的 SSH 密钥将自动使用。这是从自动化系统访问非公开 Git 存储库最常见的方式，因为它允许在没有交互式提示的情况下访问私有存储库。

如果使用 HTTP/HTTPS 协议或任何其他使用用户名/密码凭据的协议，请配置 Git 凭据存储以选择适合您环境的凭据来源。

选择修订版

默认情况下，OpenTofu 将克隆并使用选定存储库中的默认分支（由 HEAD 引用）。您可以使用 ref 参数覆盖此行为。ref 参数的值可以是 git checkout 命令接受的任何引用，例如分支、SHA-1 哈希（简短或完整）或标签名称。有关可能值的完整列表，请参阅 Git 工具 - 修订版选择，位于 Git 手册中。

代码块
# select a specific tag
module "vpc" {
  source = "git::https://example.com/vpc.git?ref=v1.2.0"
}

# directly select a commit using its SHA-1 hash
module "storage" {
  source = "git::https://example.com/storage.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"
}

浅克隆

对于较大的存储库，您可能更喜欢只进行浅克隆，以减少检索远程存储库所需的时间。

depth URL 参数对应于 git clone 的 --depth 参数，告诉 Git 创建一个浅克隆，其历史记录被截断，只保留指定数量的提交。

但是，由于浅克隆需要不同的 Git 协议行为，因此设置 depth 参数会使 OpenTofu 将您的 ref 参数（如果有）传递给 git clone 的 --branch 参数。这意味着它必须指定远程存储库已知的命名分支或标签，并且原始提交 ID 是不可接受的。

由于 OpenTofu 仅使用最近选择的提交来查找您指定模块的源代码，因此通常将 depth 设置为除 1 之外的任何值都没有用。

"scp-like" 地址语法

当通过 SSH 使用 Git 时，我们建议使用 ssh:// 前缀的 URL 格式，以保持与所有其他 URL 式 git 地址格式的一致性。您可以选择使用替代的 "scp-like" 语法，在这种情况下，您必须省略 ssh:// 方案部分，只包含 git:: 部分。例如

代码块
module "storage" {
  source = "git::[email protected]:storage.git"
}

如果您使用 ssh:// URL 方案，则 OpenTofu 将假定冒号标志着端口号的开始，而不是路径的开始。这与 Git 本身如何解释这些不同形式的方式相匹配，除了 OpenTofu 特定的 git:: 选择器前缀之外。

通用 Mercurial 存储库

您可以通过在地址前加上特殊的 hg:: 前缀来使用任意 Mercurial 存储库。在此前缀之后，可以指定任何有效的 Mercurial URL 来选择 Mercurial 支持的协议之一。

代码块
module "vpc" {
  source = "hg::http://example.com/vpc.hg"
}

OpenTofu 通过运行 hg clone 从 Mercurial 存储库安装模块，因此它将尊重您系统上设置的任何本地 Mercurial 配置，包括凭据。要访问非公开存储库，请使用该存储库的合适凭据配置 Mercurial。

如果您使用 SSH 协议，则任何已配置的 SSH 密钥将自动使用。这是从自动化系统访问非公开 Mercurial 存储库最常见的方式，因为它允许在没有交互式提示的情况下访问私有存储库。

选择修订版

您可以使用可选的 ref 参数选择非默认分支或标签

代码块
module "vpc" {
  source = "hg::http://example.com/vpc.hg?ref=v1.2.0"
}

HTTP URL

当您使用 HTTP 或 HTTPS URL 时，OpenTofu 将对给定 URL 发出 GET 请求，该请求可以返回另一个源地址。这种间接方式允许使用 HTTP URL 作为更复杂的模块源地址的某种 "虚荣重定向"。

OpenTofu 将在发送 GET 请求之前，在给定 URL 后追加一个额外的查询字符串参数 tofu-get=1，允许服务器在 OpenTofu 请求时选择性地返回不同的结果。

如果响应成功（200 范围内的状态代码），OpenTofu 会按以下顺序查找下一个要访问的地址

名为 X-Terraform-Get 的响应标头字段的值。
如果响应是 HTML 页面，则是一个名为 tofu-get 的 meta 元素。
代码块
```
<meta name="tofu-get" content="github.com/hashicorp/example" />
```

在任何情况下，结果都会被解释为另一个模块源地址，使用本页其他地方记录的格式之一。

如果 HTTP/HTTPS URL 需要身份验证凭据，请使用 .netrc 文件配置凭据。默认情况下，OpenTofu 会在您的 HOME 目录中搜索 .netrc 文件。但是，您可以通过设置 NETRC 环境变量来覆盖默认的文件系统位置。有关 .netrc 格式的信息，请参阅在 curl 中使用它的文档。

通过 HTTP 获取存档

作为一种特殊情况，如果 OpenTofu 检测到 URL 具有与存档文件格式关联的常见文件扩展名，那么它将绕过上面描述的特殊 tofu-get=1 重定向，而是直接使用引用的存档的内容作为模块源代码。

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

OpenTofu 识别此特殊行为的扩展名是

zip
tar.bz2 和 tbz2
tar.gz 和 tgz
tar.xz 和 txz

如果您的 URL没有这些扩展名，但仍然引用了存档，请使用 archive 参数强制执行这种解释

代码块
module "vpc" {
  source = "https://example.com/vpc-module?archive=zip"
}

注意

如果存档文件的内容是一个目录，您需要在模块源中包含该目录。有关更多信息，请阅读模块在包子目录中部分。

S3 存储桶

您可以使用存储在 S3 中的存档作为模块源，方法是在特殊 s3:: 前缀后加上 S3 存储桶对象 URL。

代码块
module "consul" {
  source = "s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/vpc.zip"
}

注意

AWS 的 us-east-1 区域中的存储桶必须使用主机名 s3.amazonaws.com（而不是 s3-us-east-1.amazonaws.com）。

s3:: 前缀会导致 OpenTofu 在访问给定 URL 时使用 AWS 风格的身份验证。因此，此方案也可能适用于其他模拟 S3 API 的服务，只要它们以与 AWS 相同的方式处理身份验证即可。

生成的對象必須是一個與標準 HTTP 上的存檔相同文件擴展名的存檔。OpenTofu 將解壓縮存檔以獲取模塊源樹。

模塊安裝程序在以下位置查找 AWS 憑據，當多個憑據可用時，優先使用列表中較早的憑據。

AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 環境變數。
您主目錄中 .aws/credentials 文件中的默認配置文件。
如果在 EC2 實例上運行，則與實例的 IAM 實例配置文件關聯的臨時憑據。

GCS 儲存桶

您可以使用存儲在 Google Cloud Storage 中的存檔作為模塊源，方法是使用特殊的前綴 gcs::，後跟 GCS 儲存桶對象 URL。

例如

gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH_TO_MODULE
gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH/TO/module.zip

代码块
module "consul" {
  source = "gcs::https://www.googleapis.com/storage/v1/modules/foomodule.zip"
}

模塊安裝程序使用 Google Cloud SDK 進行 GCS 身份驗證。您可以使用以下任何方法設置 Google Cloud Platform 憑據。

將 GOOGLE_OAUTH_ACCESS_TOKEN 環境變數設置為原始 Google Cloud Platform OAuth 訪問令牌。
在 GOOGLE_APPLICATION_CREDENTIALS 環境變數中輸入您的服務帳戶密鑰文件的路徑。
如果您從 GCE 實例運行 OpenTofu，則默認憑據會自動可用。有關更多詳細信息，請參閱為實例創建和啟用服務帳戶。
在您的計算機上，您可以通過運行 gcloud auth application-default login 來使您的 Google 身份可用。

包子目錄中的模塊

當模塊的源是版本控制存儲庫或存檔文件（通常稱為“包”）時，模塊本身可能位於相對於包根目錄的子目錄中。

OpenTofu 解釋特殊雙斜杠語法，表示該點後的其餘路徑是包中的子目錄。例如

hashicorp/consul/aws//modules/consul-cluster
git::https://example.com/network.git//modules/vpc
https://example.com/network-module.zip//modules/vpc
s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/network.zip//modules/vpc

如果源地址具有參數（例如版本控制源支持的 ref 參數），則子目錄部分必須位於這些參數之前。

git::https://example.com/network.git//modules/vpc?ref=v1.2.0
github.com/hashicorp/example//modules/vpc?ref=v1.2.0

OpenTofu 仍然會將整個包提取到本地磁盤，但會從子目錄中讀取模塊。因此，包的子目錄中的模塊可以使用本地路徑到另一個模塊，只要它位於相同包中即可。

支持變量和本地評估

隨著項目複雜性和需求的增加，明智的做法是在模塊源和版本字段中考慮使用本地變量和變量。

許多組織使用單個存儲庫模式進行模塊管理。

代码块
locals {
	modules_repo = "github.com/myorg/tofu-modules/"
	modules_version = "?ref=v1.20.4"
}

module "storage" {
  source = "${local.modules_repo}/storage${local.modules_version}"
}

module "compute" {
  source = "${local.modules_repo}/compute${local.modules_version}"
}

然後，很容易更新修補程序版本的版本，或切換到存儲庫的分支。

注意

源和版本字段可能不包含對狀態或提供程序定義函數中數據的任何引用。所有值必須能夠在 tofu init 期間在狀態可用之前解析。

模块源

本地路径​

模块注册表​

GitHub​

Bitbucket​

通用 Git 存储库​

选择修订版​

浅克隆​

"scp-like" 地址语法​

通用 Mercurial 存储库​

选择修订版​

HTTP URL​

通过 HTTP 获取存档​

S3 存储桶​

GCS 儲存桶​

包子目錄中的模塊​

支持變量和本地評估​

本地路径

模块注册表

GitHub

Bitbucket

通用 Git 存储库

选择修订版

浅克隆

"scp-like" 地址语法

通用 Mercurial 存储库

选择修订版

HTTP URL

通过 HTTP 获取存档

S3 存储桶

GCS 儲存桶

包子目錄中的模塊

支持變量和本地評估