可重複使用的模組最佳做法

本文件提供使用可重複使用的 Terraform 模組時應考量的規範和建議。

本指南並非 Terraform 的介紹。如要瞭解如何搭配使用 Terraform 和 Google Cloud，請參閱「開始使用 Terraform」。

在模組中啟用必要的 API

Terraform 模組可使用 google_project_service 資源或 project_services 模組啟用任何必要服務。加入 API 啟用功能，可讓示範更輕鬆。

  • 如果模組中包含 API 啟用功能，則必須透過公開預設為 true 的 enable_apis 變數，才能停用 API 啟用功能。

  • 如果模組包含 API 啟用功能，則 API 啟用功能必須將 disable_services_on_destroy 設為 false，因為這個屬性在使用模組的多個例項時，可能會導致問題。

    例如：

    module "project-services" {
  source  = "terraform-google-modules/project-factory/google//modules/project_services"
  version = "~> 12.0"

  project_id  = var.project_id
  enable_apis = var.enable_apis

  activate_apis = [
    "compute.googleapis.com",
    "pubsub.googleapis.com",
  ]
  disable_services_on_destroy = false
}

納入擁有者檔案

針對所有共用模組，請加入 OWNERS 檔案 (或 GitHub 上的 CODEOWNERS)，記錄模組的負責人。任何合併要求都必須經過擁有者核准。

發布標記版本

有時模組需要進行重大變更，您必須向使用者說明影響，讓他們將設定釘選至特定版本。

請務必在標記或發布新版本時，確保共用模組遵循 SemVer 2.0.0。

參照模組時，請使用版本限制條件將檔案繫結至主要版本。例如：

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 20.0"
}

不要設定提供者或後端

共用模組不得設定提供者或後端。請改為在根模組中設定提供者和後端。

針對共用模組，請在 required_providers 區塊中定義必要的最低供應器版本，如下所示：

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.0.0"
    }
  }
}

除非另有證明，否則假設新供應器版本可正常運作。

將標籤做為變數公開

允許透過模組介面靈活地標示資源。建議您提供 labels 變數，並將預設值設為空白地圖，如下所示：

variable "labels" {
  description = "A map of labels to apply to contained resources."
  default     = {}
  type        = "map"
}

公開所有資源的輸出內容

變數和輸出內容可讓您推斷模組和資源之間的依附關係。如果沒有任何輸出內容，使用者就無法依據 Terraform 設定正確排序模組。

針對共用模組中定義的每項資源，至少包含一個參照該資源的輸出內容。

使用內嵌子模組處理複雜的邏輯

  • 內嵌模組可讓您將複雜的 Terraform 模組整理為較小的單位，並移除重複的常用資源。
  • 將內嵌模組放在 modules/$modulename 中。
  • 將內嵌模組視為私人，不供外部模組使用，除非共用模組的說明文件另有說明。
  • Terraform 不會追蹤重構的資源。如果您一開始在頂層模組中使用多個資源，然後將這些資源推送至子模組，Terraform 會嘗試重新建立所有重構的資源。為減輕這種行為，請在重構時使用 moved 區塊。
  • 內部模組定義的輸出內容不會自動公開。如要分享內部模組的輸出內容，請重新匯出這些模組。

後續步驟