本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

程式碼基底結構與組織的最佳做法

隨著 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 可以從本地相對路徑或遠程存儲庫加載模塊。如果您希望模塊被許多配置重複使用，請將其放置在其自己的版本控制存儲庫中。重要的是要保持模塊樹相對平坦，以便更容易以不同的組合重複使用模塊。

地形可重複使用的模塊佈局基本示例：

.
├── 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 配置之間提供可移植性和可重用性。

對於共享模塊，請在中的 required_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
}

使用預設標籤

將標籤指派給所有可接受標籤的資源。地形表單 AWS 提供者有一個 aws_default_tags 資料來源，您應該在根模組內使用它。

請考慮將必要的標籤新增至 Terraform 模組所建立的所有資源。以下是可能附加的標籤清單：

符合地形登錄要求

模塊存儲庫必須滿足以下所有要求，以便可以將其發佈到 Terraform 註冊表。

即使您不打算在短期內將模組發佈到登錄，也應始終遵循這些要求。這樣，您可以稍後將模組發佈到登錄，而不必變更存放庫的組態和結構。

如需詳細資訊，請參閱 Terraform 文件中的準備模組存放庫。

使用建議的模組來源

Terraform 使用模塊中的source參數來查找和下載子模塊的源代碼。

我們建議您針對密切相關的模組使用本機路徑，這些模組的主要目的是分解重複的程式碼元素，並針對多個組態共用的模組使用原生 Terraform 模組登錄或 VCS 提供程式。

下列範例說明共用模組最常見和建議的來源類型。登錄模組支援版本控制。您應該一律提供特定版本，如下列範例所示。

登錄檔

地形註冊表：

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

  ...

}

通過固定提交哈希值，您可以避免從容易受到供應鏈攻擊的公共註冊表中漂移。

醫護機構地形：

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

  ...

  enable_karpenter = true
}

地形企業：

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 線條，格式化和代碼掃描添加為本地計算機上的掛鉤。鉤子在每個 Git 提交上運行，如果檢查未通過，則提交失敗。

將樣式和品質檢查移至本機預先提交掛鉤可在變更之前向開發人員提供快速回饋。標準成為編碼工作流程的一部分。