Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Mejores prácticas para la estructura y organización de la base de código

La estructura y la organización adecuadas de la base de código son fundamentales a medida que el uso de Terraform crece en grandes equipos y empresas. Una base de código bien diseñada permite la colaboración a escala y, al mismo tiempo, mejora la capacidad de mantenimiento.

Esta sección proporciona recomendaciones sobre la modularidad de Terraform, las convenciones de nomenclatura, la documentación y los estándares de codificación que respaldan la calidad y la coherencia.

Las directrices incluyen dividir la configuración en módulos reutilizables por entorno y componentes, establecer convenciones de nomenclatura mediante el uso de prefijos y sufijos, documentar los módulos y explicar con claridad las entradas y salidas, y aplicar reglas de formato coherentes mediante comprobaciones de estilo automatizadas.

Otras buenas prácticas incluyen la organización lógica de los módulos y recursos en una jerarquía estructurada, la catalogación de los módulos públicos y privados en la documentación y la abstracción de los detalles de implementación innecesarios en los módulos para simplificar el uso.

Al implementar pautas de estructura de código base en torno a la modularidad, la documentación, los estándares y la organización lógica, puede respaldar una amplia colaboración entre los equipos y, al mismo tiempo, mantener Terraform mantenible a medida que el uso se extiende por toda la organización. Al aplicar las convenciones y los estándares, puede evitar la complejidad de una base de código fragmentada.

Implemente una estructura de repositorio estándar

Se recomienda implementar el siguiente diseño de repositorio. La estandarización de estas prácticas de coherencia en todos los módulos mejora la capacidad de descubrimiento, la transparencia, la organización y la confiabilidad, al tiempo que permite la reutilización en muchas configuraciones de Terraform.

Estructura del módulo raíz

Terraform siempre se ejecuta en el contexto de un único módulo raíz. Una configuración completa de Terraform consta de un módulo raíz y un árbol de módulos secundarios (que incluye los módulos a los que llama el módulo raíz, cualquier módulo llamado por esos módulos, etc.).

Ejemplo básico del diseño del módulo raíz de Terraform:

.
├── data.tf
├── envs
│   ├── dev
│   │   └── terraform.tfvars
│   ├── prod
│   │   └── terraform.tfvars
│   └── test
│       └── terraform.tfvars
├── locals.tf
├── main.tf
├── outputs.tf
├── providers.tf
├── README.md
├── terraform.tfvars
├── variables.tf
└── versions.tf

Estructura de módulo reutilizable

Los módulos reutilizables siguen los mismos conceptos que los módulos raíz. Para definir un módulo, cree un nuevo directorio para él y coloque los .tf archivos en su interior, del mismo modo que definiría un módulo raíz. Terraform puede cargar módulos desde rutas relativas locales o desde repositorios remotos. Si espera que un módulo se reutilice en muchas configuraciones, colóquelo en su propio repositorio de control de versiones. Es importante mantener el árbol de módulos relativamente plano para que sea más fácil reutilizar los módulos en diferentes combinaciones.

Ejemplo básico de diseño de módulos reutilizables de Terraform:

.
├── data.tf
├── examples
│   ├── multi-az-new-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── vpc.tf
│   └── single-az-existing-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   └── versions.tf
├── iam.tf
├── locals.tf
├── main.tf
├── outputs.tf
├── README.md
├── variables.tf
└── versions.tf

Estructura de modularidad

En principio, puede combinar cualquier recurso y otras construcciones en un módulo, pero el uso excesivo de módulos anidados y reutilizables puede hacer que la configuración general de Terraform sea más difícil de entender y mantener, por lo que debe utilizar estos módulos con moderación.

Cuando tenga sentido, divida su configuración en módulos reutilizables que aumenten el nivel de abstracción. Para ello, describa un nuevo concepto de su arquitectura que se construya a partir de tipos de recursos.

Al modular la infraestructura en definiciones reutilizables, opte por conjuntos lógicos de recursos en lugar de componentes individuales o colecciones demasiado complejas.

No agrupe recursos individuales

No debes crear módulos que sean envoltorios delgados alrededor de otros tipos de recursos únicos. Si tienes problemas para encontrar un nombre para tu módulo que sea diferente del nombre del tipo de recurso principal que contiene, es probable que tu módulo no esté creando una nueva abstracción, sino que esté añadiendo complejidad innecesaria. En su lugar, usa el tipo de recurso directamente en el módulo de llamada.

Encapsula las relaciones lógicas

Agrupe conjuntos de recursos relacionados, como los fundamentos de las redes, los niveles de datos, los controles de seguridad y las aplicaciones. Un módulo reutilizable debe encapsular las partes de la infraestructura que funcionan juntas para habilitar una capacidad.

Mantenga la herencia estable

Cuando anide módulos en subdirectorios, evite profundizar más de uno o dos niveles. Las estructuras de herencia profundamente anidadas complican las configuraciones y la solución de problemas. Los módulos deben basarse en otros módulos, no construir túneles a través de ellos.

Al centrar los módulos en agrupaciones de recursos lógicos que representan patrones de arquitectura, los equipos pueden configurar rápidamente bases de infraestructura confiables. Equilibre la abstracción sin sobreingeniería ni simplificación excesivas.

Recursos de referencia en los productos

Para cada recurso que se defina en un módulo reutilizable, incluya al menos un resultado que haga referencia al recurso. Las variables y los resultados permiten inferir las dependencias entre los módulos y los recursos. Sin ningún resultado, los usuarios no pueden ordenar correctamente su módulo en relación con sus configuraciones de Terraform.

Los módulos bien estructurados que proporcionan la coherencia del entorno, las agrupaciones con objetivos específicos y las referencias de recursos exportadas permiten la colaboración a escala de Terraform en toda la organización. Los equipos pueden armar la infraestructura a partir de componentes reutilizables.

No configure los proveedores

Si bien los módulos compartidos heredan los proveedores de los módulos de llamada, los módulos no deberían configurar los ajustes del proveedor por sí mismos. Evite especificar bloques de configuración del proveedor en los módulos. Esta configuración solo debe declararse una vez a nivel mundial.

Declare los proveedores obligatorios

Si bien las configuraciones de los proveedores se comparten entre los módulos, los módulos compartidos también deben declarar sus propios requisitos de proveedor. Esta práctica permite a Terraform asegurarse de que haya una única versión del proveedor que sea compatible con todos los módulos de la configuración y especificar la dirección de origen que sirve como identificador global (independiente del módulo) del proveedor. Sin embargo, los requisitos del proveedor específicos del módulo no especifican ninguno de los ajustes de configuración que determinan a qué puntos finales remotos accederá el proveedor, como un. Región de AWS

Al declarar los requisitos de versión y evitar la configuración de proveedores codificada, los módulos proporcionan portabilidad y reutilización en todas las configuraciones de Terraform que utilizan proveedores compartidos.

En el caso de los módulos compartidos, defina las versiones de proveedor mínimas requeridas en un bloque required_providers. versions.tf

Para declarar que un módulo requiere una versión determinada del AWS proveedor, usa un required_providers bloque dentro de un bloque: terraform

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0.0"
    }
  }
}

Si un módulo compartido solo admite una versión específica del AWS proveedor, utilice el operador de restricción pesimista (~>), que permite que solo se incremente el componente de la versión que se encuentra más a la derecha:

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

En este ejemplo, ~> 4.0 permite la instalación de y, pero no. 4.57.1 4.67.0 5.0.0 Para obtener más información, consulte Sintaxis de restricciones de versión en la HashiCorp documentación.

Siga las convenciones de nomenclatura

Los nombres descriptivos y claros simplifican la comprensión de las relaciones entre los recursos del módulo y el propósito de los valores de configuración. La coherencia con las pautas de estilo mejora la legibilidad tanto para los usuarios como para los encargados del mantenimiento del módulo.

Siga las pautas para la denominación de los recursos

Siga las pautas para la denominación de las variables

Utilice los recursos de archivos adjuntos

Algunos recursos tienen pseudorecursos integrados como atributos. Siempre que sea posible, debes evitar el uso de estos atributos de recursos integrados y, en su lugar, usar el recurso único para adjuntar ese pseudorecurso. Estas relaciones de recursos pueden provocar cause-and-effect problemas exclusivos para cada recurso.

Uso de un atributo incrustado (evite este patrón):

resource "aws_security_group" "allow_tls" {
  ...
  ingress {
    description      = "TLS from VPC"
    from_port        = 443
    to_port          = 443
    protocol         = "tcp"
    cidr_blocks      = [aws_vpc.main.cidr_block]
    ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

Uso de recursos de archivos adjuntos (preferido):

resource "aws_security_group" "allow_tls" {
  ...
}

resource "aws_security_group_rule" "example" {
  type              = "ingress"
  description      = "TLS from VPC"
  from_port        = 443
  to_port          = 443
  protocol         = "tcp"
  cidr_blocks      = [aws_vpc.main.cidr_block]
  ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  security_group_id = aws_security_group.allow_tls.id
}

Usa etiquetas predeterminadas

Asigne etiquetas a todos los recursos que puedan aceptarlas. El AWS proveedor de Terraform tiene una fuente de datos aws_default_tags que debe usar dentro del módulo raíz.

Considere agregar las etiquetas necesarias a todos los recursos creados por un módulo de Terraform. Esta es una lista de posibles etiquetas para adjuntar:

Cumple con los requisitos de registro de Terraform

Un repositorio de módulos debe cumplir todos los requisitos siguientes para poder publicarse en un registro de Terraform.

Siempre debe seguir estos requisitos, incluso si no planea publicar el módulo en un registro a corto plazo. De este modo, puede publicar el módulo en un registro más adelante sin tener que cambiar la configuración y la estructura del repositorio.

Para obtener más información, consulte Preparación de un repositorio de módulos en la documentación de Terraform.

Utilice las fuentes de módulos recomendadas

Terraform usa el source argumento de un bloque de módulos para buscar y descargar el código fuente de un módulo secundario.

Le recomendamos que utilice rutas locales para los módulos estrechamente relacionados que tengan como objetivo principal descartar los elementos de código repetidos, y que utilice un registro de módulos nativo de Terraform o un proveedor de VCS para los módulos que estén destinados a ser compartidos por varias configuraciones.

Los siguientes ejemplos ilustran los tipos de fuentes más comunes y recomendados para compartir módulos. Los módulos de registro admiten el control de versiones. Siempre debe proporcionar una versión específica, como se muestra en los siguientes ejemplos.

Registro

Registro de Terraform:

module "lambda" {
  source = "github.com/terraform-aws-modules/terraform-aws-lambda.git?ref=e78cdf1f82944897ca6e30d6489f43cf24539374" #--> v4.18.0

  ...

}

Al fijar los hashes de confirmación, puede evitar desviarse de los registros públicos, que son vulnerables a los ataques a la cadena de suministro.

HCP Terraform:

module "eks_karpenter" {
  source = "app.terraform.io/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Terraform Enterprise:

module "eks_karpenter" {
  source = "terraform.mydomain.com/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Proveedores de VCS

Los proveedores de VCS apoyan el ref argumento a favor de seleccionar una revisión específica, como se muestra en los siguientes ejemplos.

GitHub (HTTPS):

module "eks_karpenter" {
  source = "github.com/my-org/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Repositorio Git genérico (HTTPS):

module "eks_karpenter" {
  source = "git::https://example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Repositorio Git genérico (SSH):

module "eks_karpenter" {
  source = "git::ssh://username@example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Siga los estándares de codificación

Aplique reglas y estilos de formato de Terraform consistentes en todos los archivos de configuración. Haga cumplir los estándares mediante comprobaciones de estilo automatizadas en las canalizaciones de CI/CD. Cuando incorporas las mejores prácticas de codificación en los flujos de trabajo de los equipos, las configuraciones siguen siendo legibles, fáciles de mantener y colaborativas, ya que su uso se extiende ampliamente en la organización.

Sigue las pautas de estilo

Configura enlaces previos a la confirmación

Configura enlaces de preconfirmación del lado del cliente que se ejecuten terraform fmt tflintcheckov, y otros escaneos de código y comprobaciones de estilo antes de permitir las confirmaciones. Esta práctica te ayuda a validar el cumplimiento de los estándares de forma más temprana en los flujos de trabajo de los desarrolladores.

Utilice marcos de preconfirmación, como la confirmación previa, para añadir el linting, el formateo y el escaneo de código de Terraform a modo de gancho en su máquina local. Los Hooks se ejecutan en cada confirmación de Git y fallan en la confirmación si las comprobaciones no se aprueban.

Al trasladar los controles de estilo y calidad a los enlaces locales previos a la confirmación, los desarrolladores reciben información rápida antes de introducir los cambios. Los estándares pasan a formar parte del flujo de trabajo de codificación.