Prácticas recomendadas para los módulos raíz

En este documento se ofrecen directrices y recomendaciones que debes tener en cuenta al usar módulos raíz.

Las configuraciones raíz o los módulos raíz son los directorios de trabajo desde los que ejecutas la CLI de Terraform. Asegúrate de que las configuraciones raíz cumplan los siguientes estándares (y las directrices de Terraform anteriores, si procede). Las recomendaciones explícitas para los módulos raíz sustituyen a las directrices generales.

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.

Minimiza el número de recursos de cada módulo raíz

Es importante evitar que una configuración raíz única crezca demasiado, con demasiados recursos almacenados en el mismo directorio y estado. Todos los recursos de una configuración raíz concreta se actualizan cada vez que se ejecuta Terraform. Esto puede provocar una ejecución lenta si se incluyen demasiados recursos en un solo estado. Como regla general, no incluyas más de 100 recursos (y, lo ideal, solo unas pocas docenas) en un mismo estado.

Usar directorios independientes para cada aplicación

Para gestionar las aplicaciones y los proyectos de forma independiente, coloque los recursos de cada aplicación y proyecto en sus propios directorios de Terraform. Un servicio puede representar una aplicación concreta o un servicio común, como una red compartida. Anida todo el código de Terraform de un servicio concreto en un directorio (incluidos los subdirectorios).

Dividir las aplicaciones en subdirectorios específicos de cada entorno

Cuando implementes servicios en Google Cloud, divide la configuración de Terraform del servicio en dos directorios de nivel superior: un directorio modules que contenga la configuración real del servicio y un directorio environments que contenga las configuraciones raíz de 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

Usar directorios de entorno

Para compartir código entre entornos, haz referencia a los módulos. Por lo general, se trata de un módulo de servicio que incluye la configuración base compartida de Terraform para el servicio. En los módulos de servicio, codifica de forma rígida las entradas comunes y solo requiere las entradas específicas del entorno como variables.

Cada directorio de entorno debe contener los siguientes archivos:

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

Cada directorio de entorno (dev, qa y prod) corresponde a un espacio de trabajo de Terraform predeterminado y despliega una versión del servicio en ese entorno. Estos espacios de trabajo aislan los recursos específicos del entorno en sus propios contextos. Usar solo el espacio de trabajo predeterminado.

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

  • Puede ser difícil inspeccionar la configuración de cada espacio de trabajo.
  • No se recomienda tener un solo backend compartido para varios espacios de trabajo, ya que se convierte en un único punto de fallo si se usa para separar entornos.
  • Aunque se puede reutilizar el código, resulta más difícil de leer, ya que hay que cambiar en función de la variable del espacio de trabajo actual (por ejemplo, terraform.workspace == "foo" ? this : that).

Para obtener más información, consulta las siguientes secciones:

Exponer salidas a través del estado remoto

Asegúrate de exponer las salidas útiles de las instancias de módulos de un módulo raíz.

Por ejemplo, el siguiente fragmento de código transfiere el ID de proyecto de la instancia del módulo de la fábrica de proyectos como salida 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 las salidas de nivel de módulo raíz.

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

# 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"
  ...
}

En ocasiones, como cuando se invoca un módulo de servicio compartido desde directorios de entorno, es adecuado volver a exportar todo el módulo secundario, como se indica a continuación:

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

Fijar a versiones secundarias de proveedores

En los módulos raíz, declara cada proveedor y fija una versión menor. Esto permite actualizar automáticamente a nuevas versiones de parches sin dejar de mantener un objetivo sólido. Para mantener la coherencia, asigna el nombre versions.tf al archivo de versiones.

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

Almacenar variables en un archivo tfvars

En el caso de los módulos raíz, proporcione variables mediante un archivo de variables .tfvars. Para mantener la coherencia, los archivos de variables deben llamarse terraform.tfvars.

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

Revisar archivo .terraform.lock.hcl

En el caso de los módulos raíz, el archivo .terraform.lock.hcl dependency lock debe registrarse en el control de código fuente. De esta forma, se pueden monitorizar y revisar los cambios en las selecciones de proveedores de una configuración determinada.

Siguientes pasos