有关可重复使用的模块的最佳实践

本文档提供了使用可重复使用的 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 v2.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 块。
  • 内部模块定义的输出不会自动公开。如需共享内部模块的输出，请重新导出这些模块。

后续步骤