本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

代码库结构和组织的最佳实践

随着大型团队和企业使用Terraform的增长，适当的代码库结构和组织至关重要。架构良好的代码库可实现大规模协作，同时增强可维护性。

本节提供有关支持质量和一致性的 Terraform 模块化、命名约定、文档和编码标准的建议。

指导包括按环境和组件将配置分解为可重复使用的模块，通过使用前缀和后缀建立命名约定，记录模块并清楚地解释输入和输出，以及使用自动样式检查来应用一致的格式化规则。

其他最佳实践包括在结构化层次结构中以逻辑方式组织模块和资源，在文档中对公共和私有模块进行分类，以及在模块中抽象不必要的实现细节以简化使用。

通过围绕模块化、文档、标准和逻辑组织实施代码库结构指南，您可以支持跨团队的广泛协作，同时随着使用情况在整个组织中的普及，Terraform 保持可维护性。通过强制执行惯例和标准，可以避免零碎代码库的复杂性。

实现标准存储库结构

我们建议您实现以下存储库布局。跨模块对这些一致性实践进行标准化可以提高可发现性、透明度、组织性和可靠性，同时支持在许多 Terraform 配置中重复使用。

根模块结构

Terraform 总是在单个根模块的上下文中运行。完整的 Terraform 配置由根模块和子模块树（包括根模块调用的模块、这些模块调用的任何模块等）组成。

Terraform 根模块布局基本示例：

.
├── data.tf
├── envs
│   ├── dev
│   │   └── terraform.tfvars
│   ├── prod
│   │   └── terraform.tfvars
│   └── test
│       └── terraform.tfvars
├── locals.tf
├── main.tf
├── outputs.tf
├── providers.tf
├── README.md
├── terraform.tfvars
├── variables.tf
└── versions.tf

可重复使用的模块结构

可重复使用的模块遵循与根模块相同的概念。要定义模块，请为其创建一个新目录并将.tf文件放入其中，就像定义根模块一样。Terraform 可以从本地相对路径或远程存储库加载模块。如果您希望某个模块可以被许多配置重复使用，请将其放在自己的版本控制存储库中。保持模块树相对平坦很重要，这样可以更轻松地以不同的组合重复使用模块。

Terraform 可重复使用的模块布局基本示例：

.
├── data.tf
├── examples
│   ├── multi-az-new-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── vpc.tf
│   └── single-az-existing-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   └── versions.tf
├── iam.tf
├── locals.tf
├── main.tf
├── outputs.tf
├── README.md
├── variables.tf
└── versions.tf

模块化结构

原则上，您可以将任何资源和其他结构组合到一个模块中，但是过度使用嵌套和可重用的模块会使您的整体 Terraform 配置更难理解和维护，因此请谨慎使用这些模块。

如果有意义，可以将您的配置分解为可重复使用的模块，这些模块通过描述架构中由资源类型构造的新概念来提高抽象级别。

当您将基础设施模块化为可重复使用的定义时，应瞄准逻辑资源集，而不是单个组件或过于复杂的集合。

不要封装单个资源

你不应该创建围绕其他单一资源类型的薄包装模块。如果你在为模块找到与其中的主资源类型名称不同的名称时遇到困难，那么你的模块可能没有创建新的抽象，而是增加了不必要的复杂性。相反，直接在调用模块中使用资源类型。

封装逻辑关系

对相关资源进行分组，例如网络基础、数据层、安全控制和应用程序。可重复使用的模块应封装协同工作的基础架构部分，以实现一项功能。

保持继承不变

将模块嵌套在子目录中时，请避免深度超过一两个级别。深度嵌套的继承结构使配置和故障排除变得复杂。模块应该建立在其他模块之上，而不是通过它们构建隧道。

通过将模块重点放在代表架构模式的逻辑资源分组上，团队可以快速配置可靠的基础架构。在不进行过度设计或过度简化的情况下平衡抽象。

产出中的参考资源

对于在可重用模块中定义的每个资源，至少包括一个引用该资源的输出。变量和输出允许您推断模块和资源之间的依赖关系。如果没有任何输出，用户就无法根据他们的 Terraform 配置正确订购您的模块。

结构良好的模块可提供环境一致性、以目的为导向的分组和导出的资源引用，可实现组织范围内的 Terraform 大规模协作。团队可以利用可重复使用的构造块组装基础架构。

不要配置提供商

尽管共享模块继承调用模块的提供程序，但模块不应自行配置提供程序设置。避免在模块中指定提供程序配置块。此配置只能在全局声明一次。

申报所需的提供商

尽管提供程序配置在模块之间共享，但共享模块还必须声明自己的提供者要求。这种做法使 Terraform 能够确保提供程序的单一版本与配置中的所有模块兼容，并指定用作提供程序全局（与模块无关）标识符的源地址。但是，模块特定的提供程序要求并未指定任何用于确定提供程序将访问哪些远程端点的配置设置，例如。 AWS 区域

通过声明版本要求并避免使用硬编码的提供程序配置，模块使用共享提供程序提供跨Terraform配置的可移植性和可重用性。

对于共享模块，请在中的 requi red_providers 块中定义所需的最低提供者版本。versions.tf

要声明模块需要特定版本的 AWS 提供程序，请在required_providers块内使用一个terraform块：

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0.0"
    }
  }
}

如果共享模块仅支持 AWS 提供程序的特定版本，请使用悲观约束运算符 (~>)，它只允许最右边的版本组件递增：

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

在本示例中，~> 4.0允许安装4.57.1和，4.67.0但不允许5.0.0。有关更多信息，请参阅 HashiCorp 文档中的版本约束语法。

遵循命名惯例

清晰的描述性名称可简化您对模块中资源之间关系和配置值用途的理解。与风格指南的一致性提高了模块用户和维护者的可读性。

遵循资源命名准则

请遵循变量命名指南

使用附件资源

有些资源中嵌入了伪资源作为属性。在可能的情况下，应避免使用这些嵌入的资源属性，而是使用唯一的资源来附加该伪资源。这些资源关系可能导致每种资源都存在独特 cause-and-effect 的问题。

使用嵌入式属性（避免这种模式）：

resource "aws_security_group" "allow_tls" {
  ...
  ingress {
    description      = "TLS from VPC"
    from_port        = 443
    to_port          = 443
    protocol         = "tcp"
    cidr_blocks      = [aws_vpc.main.cidr_block]
    ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

使用附件资源（首选）：

resource "aws_security_group" "allow_tls" {
  ...
}

resource "aws_security_group_rule" "example" {
  type              = "ingress"
  description      = "TLS from VPC"
  from_port        = 443
  to_port          = 443
  protocol         = "tcp"
  cidr_blocks      = [aws_vpc.main.cidr_block]
  ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  security_group_id = aws_security_group.allow_tls.id
}

使用默认标签

为所有可以接受标签的资源分配标签。Terraform P AWS rovider 有一个 aws_default_tags 数据源，你应该在根模块中使用它。

考虑向 Terraform 模块创建的所有资源添加必要的标签。以下是可能要附加的标签列表：

满足 Terraform 注册表要求

模块存储库必须满足以下所有要求才能发布到 Terraform 注册表。

即使您不打算在短期内将模块发布到注册表，也应始终遵循这些要求。这样，您就可以稍后将模块发布到注册表，而不必更改存储库的配置和结构。

有关更多信息，请参阅 Terraform 文档中的准备模块存储库。

使用推荐的模块源

Terraform 使用模块块中的source参数来查找和下载子模块的源代码。

我们建议您对密切相关的模块使用本地路径，这些模块的主要目的是分解重复的代码元素，对于打算由多个配置共享的模块，使用原生 Terraform 模块注册表或 VCS 提供程序。

以下示例说明了共享模块的最常见和最推荐的源类型。注册表模块支持版本控制。您应始终提供特定的版本，如以下示例所示。

注册表

Terraform 注册表：

module "lambda" {
  source = "github.com/terraform-aws-modules/terraform-aws-lambda.git?ref=e78cdf1f82944897ca6e30d6489f43cf24539374" #--> v4.18.0

  ...

}

通过固定提交哈希，您可以避免偏离容易受到供应链攻击的公共注册表。

HCP Terraform：

module "eks_karpenter" {
  source = "app.terraform.io/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Terraform Enterpr

module "eks_karpenter" {
  source = "terraform.mydomain.com/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

VCS 提供商

版本控制系统（VCS）提供程序支持选择特定修订版的ref论点，如以下示例所示。

GitHub (HTTPS)：

module "eks_karpenter" {
  source = "github.com/my-org/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

通用 Git 存储库 (HTTPS)：

module "eks_karpenter" {
  source = "git::https://example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

通用 Git 存储库 (SSH)：

module "eks_karpenter" {
  source = "git::ssh://username@example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

遵循编码标准

在所有配置文件中应用一致的 Terraform 格式规则和样式。通过在 CI/CD 管道中使用自动样式检查来强制执行标准。当您将编码最佳实践嵌入到团队工作流程中时，随着使用情况在整个组织中的广泛分布，配置仍保持可读性、可维护性和协作性。

遵循风格指南

配置预提交挂钩

在允许提交之前，配置运行terraform fmt、tflintcheckov、和其他代码扫描和样式检查的客户端预提交挂钩。这种做法可以帮助您在开发人员工作流程中尽早验证标准一致性。

使用预提交框架（例如预提交）在本地计算机上将 Terraform linting、格式化和代码扫描作为挂钩添加。Hooks 会在每个 Git 提交上运行，如果检查未通过，则提交失败。

将样式和质量检查移至本地预提交挂钩可在引入更改之前向开发人员提供快速反馈。标准成为编码工作流程的一部分。