Prácticas recomendadas para los módulos reutilizables

En este documento se proporcionan directrices y recomendaciones que debes tener en cuenta al usar módulos de Terraform reutilizables.

Esta guía no es una introducción a Terraform. Para obtener una introducción al uso de Terraform con Google Cloud, consulta el artículo Empezar a usar Terraform.

Activar las APIs necesarias en los módulos

Los módulos de Terraform pueden activar los servicios necesarios mediante el recurso google_project_service o el módulo project_services. Al incluir la activación de la API, las demostraciones son más sencillas.

  • Si la activación de la API se incluye en un módulo, debe poder inhabilitarse exponiendo una variable enable_apis que tenga el valor predeterminado true.

  • Si la activación de la API se incluye en un módulo, debe definir disable_services_on_destroy como false, ya que este atributo puede provocar problemas al trabajar con varias instancias del módulo.

    Por ejemplo:

    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
}

Incluir un archivo de propietarios

En todos los módulos compartidos, incluye un archivo OWNERS (o CODEOWNERS en GitHub) en el que se indique quién es el responsable del módulo. Antes de que se combine una solicitud de extracción, el propietario debe aprobarla.

Publicar versiones etiquetadas

A veces, los módulos requieren cambios incompatibles y debes comunicar los efectos a los usuarios para que puedan fijar sus configuraciones a una versión específica.

Asegúrate de que los módulos compartidos sigan la versión 2.0.0 de SemVer cuando se etiqueten o publiquen nuevas versiones.

Cuando hagas referencia a un módulo, usa una restricción de versión para fijar la versión principal. Por ejemplo:

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

No configurar proveedores ni backends

Los módulos compartidos no deben configurar proveedores ni back-ends. En su lugar, configura los proveedores y los backends en los módulos raíz.

En el caso de los módulos compartidos, define las versiones mínimas necesarias del proveedor en un bloque required_providers, como se indica a continuación:

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

A menos que se demuestre lo contrario, se presupone que las nuevas versiones del proveedor funcionarán.

Exponer etiquetas como una variable

Permite flexibilidad en el etiquetado de recursos a través de la interfaz del módulo. Te recomendamos que proporciones una variable labels con el valor predeterminado de un mapa vacío, como se indica a continuación:

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

Exponer las salidas de todos los recursos

Las variables y las salidas te permiten inferir las dependencias entre módulos y recursos. Si no hay ninguna salida, los usuarios no podrán ordenar correctamente tu módulo en relación con sus configuraciones de Terraform.

Por cada recurso definido en un módulo compartido, incluye al menos una salida que haga referencia al recurso.

Usar submódulos insertados para una lógica compleja

  • Los módulos insertados te permiten organizar módulos de Terraform complejos en unidades más pequeñas y eliminar recursos comunes duplicados.
  • Coloca los módulos insertados en modules/$modulename.
  • Considera los módulos insertados como privados, de modo que no los usen módulos externos, a menos que la documentación del módulo compartido indique lo contrario.
  • Terraform no monitoriza los recursos refactorizados. Si empiezas con varios recursos en el módulo de nivel superior y, después, los insertas en submódulos, Terraform intentará volver a crear todos los recursos refactorizados. Para mitigar este comportamiento, usa bloques moved al refactorizar.
  • Las salidas definidas por módulos internos no se exponen automáticamente. Para compartir resultados de módulos internos, vuelve a exportarlos.

Siguientes pasos