Prácticas recomendadas para módulos reutilizables

En este documento, se proporcionan lineamientos y recomendaciones para tener en cuenta cuando uses 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 Comienza a usar Terraform.

Activa las API necesarias en módulos

Los módulos de Terraform pueden activar cualquier servicio obligatorio mediante el recurso google_project_service o el módulo project_services. Incluir la activación de API facilita las demostraciones.

  • Si la activación de la API se incluye en un módulo, la activación de la API debe inhabilitarse mediante la exposición de una variable enable_apis que se establece de forma predeterminada en true.

  • Si la activación de la API se incluye en un módulo, la activación de la API debe establecerse disable_services_on_destroy en false, ya que este atributo puede causar problemas cuando se trabaja 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
}

Incluye un archivo de propietarios

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

Lanza versiones con etiquetas

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

Asegúrate de que los módulos compartidos sigan a SemVer v2.0.0 cuando se etiqueten o lancen versiones nuevas.

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 configures proveedores ni backends

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

Para los módulos compartidos, define las versiones mínimas de los proveedores que se requieren en un bloque required_providers de la siguiente manera:

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

A menos que se pruebe lo contrario, supongamos que las nuevas versiones de los proveedores funcionarán.

Expón etiquetas como una variable

Permite la flexibilidad en el etiquetado de los recursos a través de la interfaz del módulo. Considera proporcionar una variable labels con un valor predeterminado de un mapa vacío, de la siguiente manera:

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

Expón resultados para todos los recursos

Las variables y los resultados te permiten inferir dependencias entre módulos y recursos. Sin ningún resultado, los usuarios no pueden ordenar de forma correcta tu módulo en relación con sus opciones de configuración de Terraform.

Para cada recurso definido en un módulo compartido, incluye al menos un resultado que haga referencia al recurso.

Usa submódulos intercalados para la lógica compleja

  • Los módulos intercalados te permiten organizar módulos complejos de Terraform en unidades más pequeñas y anular la duplicación de recursos comunes.
  • Coloca los módulos intercalados en modules/$modulename.
  • Trata los módulos intercalados como privados, a fin de que los módulos externos no los usen, a menos que la documentación del módulo compartido indique lo contrario.
  • Terraform no realiza un seguimiento de los recursos refactorizados. Si comienzas con varios recursos en el módulo de nivel superior y, luego, los envías a submódulos, Terraform intenta volver a crear todos los recursos refactorizados. Para mitigar este comportamiento, usa bloques moved cuando refactorices.
  • Los resultados que definen los módulos internos no se exponen de manera automática. Para compartir los resultados de los módulos internos, vuelve a exportarlos.

¿Qué sigue?