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

程式碼基礎結構和組織的最佳實務

隨著 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 組態提供可攜性和可重複使用性。

對於共用模組，請在 的 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 提供者，請使用 essimistic 限制運算子 (~>)，只允許增加最右側的版本元件：

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 AWS 提供者具有您應該在根模組內使用的 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 Enterprise：

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、checkov、 tflint和其他程式碼掃描和樣式檢查的用戶端預先遞交勾點。此實務可協助您更早在開發人員工作流程中驗證標準一致性。

使用預先遞交架構，例如預先遞交，將 Terraform linting、格式化和程式碼掃描新增為本機電腦上的掛鉤。勾點會在每個 Git 遞交上執行，如果檢查未通過，則遞交會失敗。

在引入變更之前，將樣式和品質檢查移至本機遞交前勾點可為開發人員提供快速意見回饋。標準成為編碼工作流程的一部分。