Prácticas recomendadas para módulos raíz

En este documento, se proporcionan lineamientos y recomendaciones que debes tener en cuenta cuando uses módulos raíz.

Los parámetros de configuración raíz o módulos raíz son los directorios de trabajo desde los que ejecutas la CLI de Terraform. Asegúrate de que las opciones de configuración raíz cumplan con los siguientes estándares (y con los lineamientos anteriores de Terraform, cuando corresponda). Las recomendaciones explícitas para los módulos raíz sustituyen los lineamientos generales.

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.

Minimiza la cantidad de recursos en cada módulo raíz

Es importante evitar que una sola opción de configuración raíz sea demasiado grande y cuente con demasiados recursos almacenados en el mismo directorio y estado. Todos los recursos de una opción de configuración raíz en particular se actualizan cada vez que se ejecuta Terraform. Esto puede causar una ejecución lenta si se incluyen demasiados recursos en un solo estado. Una regla general: no incluyas más de 100 recursos (lo ideal sería solo unas pocas docenas) en un solo estado.

Usa directorios separados para cada aplicación

Para administrar las aplicaciones y los proyectos de forma independiente, coloca recursos para cada aplicación y proyecto en sus propios directorios de Terraform. Un servicio puede representar una aplicación particular o un servicio común, como las redes compartidas. Anida todo el código de Terraform para un servicio en particular en un directorio (incluidos los subdirectorios).

Divide las aplicaciones en subdirectorios específicos del entorno

Cuando implementes servicios en Google Cloud, divide la configuración de Terraform para el servicio en dos directorios de nivel superior: un directorio modules que contiene la configuración real del servicio, y un directorio environments que contiene las configuraciones raíz para cada entorno.

-- SERVICE-DIRECTORY/
   -- OWNERS
   -- modules/
      -- <service-name>/
         -- main.tf
         -- variables.tf
         -- outputs.tf
         -- provider.tf
         -- README
      -- ...other…
   -- environments/
      -- dev/
         -- backend.tf
         -- main.tf

      -- qa/
         -- backend.tf
         -- main.tf

      -- prod/
         -- backend.tf
         -- main.tf

Usa directorios del entorno

Para compartir código entre entornos, consulta los módulos. Por lo general, este podría ser un módulo de servicio que incluya la configuración base compartida de Terraform para el servicio. En los módulos de servicio, codifica las entradas comunes de forma hard-coded y solo requiere entradas específicas del entorno como variables.

Cada directorio del entorno debe contener los siguientes archivos:

  • Un archivo backend.tf que declara la ubicación del estado del backend de Terraform (por lo general, Cloud Storage)
  • Un archivo main.tf que crea una instancia del módulo de servicio

Cada directorio del entorno (dev, qa, prod) corresponde a un lugar de trabajo de Terraform predeterminado y, luego, implementa una versión del servicio en ese entorno. Estos lugares de trabajo aíslan los recursos específicos del entorno en sus propios contextos. Usa solo el lugar de trabajo predeterminado.

No se recomienda tener varios lugares de trabajo de la CLI en un entorno por los siguientes motivos:

  • Puede ser difícil inspeccionar la configuración en cada lugar de trabajo.
  • No se recomienda tener un solo backend compartido para varios lugares de trabajo, ya que el backend compartido se convierte en un punto único de fallo si se usa para la separación del entorno.
  • Si bien es posible volver a usar el código, se vuelve más difícil leer el código debiendo cambiar según la variable de lugar de trabajo actual (por ejemplo, terraform.workspace == "foo" ? this : that).

Para obtener más información, consulta lo siguiente:

Expón resultados mediante el estado remoto

Asegúrate de exponer los resultados útiles de las instancias del módulo desde un módulo raíz.

Por ejemplo, el siguiente fragmento de código pasa por el resultado del ID del proyecto desde la instancia del módulo de fábrica del proyecto como resultado del módulo raíz.

# Project root module
terraform {
  backend "gcs" {
    bucket  = "BUCKET"
  }
}

module "project" {
  source  = "terraform-google-modules/project-factory/google"
  ...
}

output "project_id" {
  value       = module.project.project_id
  description = "The ID of the created project"
}

Otros entornos y aplicaciones de Terraform solo pueden hacer referencia a los resultados a nivel de módulo raíz.

Si usas el estado remoto, puedes hacer referencia a los resultados del módulo raíz. Para permitir que otras apps dependientes usen la configuración, asegúrate de exportar al estado remoto la información relacionada con los extremos de un servicio.

# Networks root module
data "terraform_remote_state" "network_project" {
  backend = "gcs"

  config = {
    bucket = "BUCKET"
  }
}

module "vpc" {
  source  = "terraform-google-modules/network/google"
  version = "~> 9.0"

  project_id   = data.terraform_remote_state.network_project.outputs.project_id
  network_name = "vpc-1"
  ...
}

A veces, como cuando se invoca un módulo de servicio compartido desde directorios de entornos, es apropiado volver a exportar todo el módulo secundario de la siguiente manera:

output "service" {
  value       = module.service
  description = "The service module outputs"
}

Fija en las versiones secundarias del proveedor

En los módulos raíz, declara cada proveedor y fija en una versión secundaria. Esto permite la actualización automática a nuevas versiones de parches y, al mismo tiempo, mantiene un objetivo sólido. Para mantener la coherencia, nombra el archivo de versiones versions.tf.

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

Almacena variables en un archivo tfvars

Para los módulos raíz, proporciona variables con un archivo de variables .tfvars. Para mantener la coherencia, nombra los archivos de variables terraform.tfvars.

No especifiques variables mediante opciones de línea de comandos alternativas de var-files o var='key=val'. Las opciones de línea de comandos son efímeras y fáciles de olvidar. El uso de un archivo de variables predeterminado es más predecible.

Revisa el archivo .terraform.lock.hcl

Para los módulos raíz, el archivo .terraform.lock.hcl de bloqueo de dependencia se debe registrar en el control de origen. Esto permite realizar un seguimiento y revisar los cambios en las selecciones de proveedores para una configuración determinada.

¿Qué sigue?