Guía Completa de Módulos de Terraform
Construye módulos de Terraform reutilizables con estructura limpia, inputs validados, outputs honestos y versionado seguro. Incluye pruebas con terraform test y Terratest, además de publicación en el Registry.
Introducción
El primer proyecto de Terraform suele verse bien: un main.tf, un puñado de recursos, listo. Después staging necesita la misma VPC con otros CIDRs. Después otro equipo quiere el mismo stack menos el bastion host. Copiar y pegar funciona una semana, hasta que alguien actualiza una copia y olvida las otras dos. Los entornos divergen y nadie sabe ya cuál archivo es el “real”.
Los módulos son la respuesta de Terraform a eso. Un módulo es solo un directorio de archivos .tf con un contrato definido: entradas en variables.tf, salidas en outputs.tf, recursos en medio. Lo llamas desde cuantos sitios quieras, pasas valores distintos y cada entorno queda sobre la misma definición.
Esta guía cubre el ciclo completo: cómo se estructura un módulo, cómo diseñar su contrato de entradas y salidas, dónde pueden vivir los módulos (local, git, registry), cómo componerlos, cómo probarlos con terraform test y Terratest, y cómo versionarlos y publicarlos para que los consumidores fijen una release conocida. El ejemplo continuo es un módulo de VPC — el clásico primer módulo — pero cada patrón aplica a lo que sea que estés encapsulando.
Cuándo usar módulos (y cuándo no)
La regla práctica: extrae un módulo la tercera vez que escribes los mismos recursos. La primera ocurrencia es código. La segunda es candidata. La tercera es duplicación que va a divergir.
Los buenos candidatos comparten tres rasgos: son una unidad coherente (una VPC, una base de datos con sus réplicas, una app con su DNS y TLS), varían por configuración y no por forma (CIDRs y tamaños distintos, no un grafo de recursos distinto), y más de un entorno o equipo los va a consumir.
Los módulos son la herramienta equivocada cuando:
- El conjunto de recursos es único. Un
aws_route53_zonesuelto no necesita un módulo envoltorio. - La abstracción supera al equipo. Un módulo que envuelve cinco recursos detrás de cuarenta variables es un segundo lenguaje que tu equipo ahora tiene que aprender. Si los consumidores necesitan leer el interior del módulo para usarlo, la abstracción falló.
- Envuelves un módulo comunitario sin añadir valor. Re-exportar
terraform-aws-modules/vpca través de tu propio wrapper delgado añade una indirección de versiones y nada más; consúmelo directamente.
Una prueba de olfato útil: si el variables.tf del módulo tiene más entradas que recursos tiene su main.tf, probablemente está sobre-abstraído.
La granularidad también tiene un modelo de costos. Cada llamada a módulo es una frontera: los datos la cruzan solo por variables y outputs, y Terraform serializa operaciones a través de ella. Los módulos finos (uno por tipo de recurso, compuestos hacia arriba) maximizan la reutilización y permiten que los equipos posean piezas de forma independiente. Los módulos gruesos (uno por entorno o app) se leen más simple y versionan una vez. La mayoría de organizaciones aterriza en el medio: módulos pequeños para primitivas compartidas como redes y clusters, un módulo delgado a nivel app que los conecta por servicio.
Anatomía de un módulo
Terraform no tiene un tipo de archivo “módulo” especial — el contrato es una convención de directorio:
modules/
└── vpc/
├── main.tf # Definiciones de recursos
├── variables.tf # Variables de entrada
├── outputs.tf # Valores de salida
├── versions.tf # Versiones requeridas de Terraform y providers
├── README.md # Documentación, tablas de inputs/outputs
├── examples/
│ └── basic/
│ └── main.tf # Ejemplo ejecutable
└── tests/
└── vpc.tftest.hcl
main.tf
main.tf contiene los recursos. Mantenlo aburrido: recursos y locals, nada de metaprogramación ingeniosa. Este es el módulo de VPC usado en toda la guía — fíjate en for_each para las subnets y en una route table privada conectada a un NAT gateway, para que las subnets privadas puedan salir realmente a internet:
locals {
public_subnet_ids = [for s in aws_subnet.public : s.id]
private_subnet_ids = [for s in aws_subnet.private : s.id]
}
resource "aws_vpc" "this" {
cidr_block = var.cidr_block
enable_dns_support = var.enable_dns_support
enable_dns_hostnames = var.enable_dns_hostnames
tags = merge({ Name = var.name }, var.tags)
}
resource "aws_subnet" "public" {
for_each = toset(var.public_subnets)
vpc_id = aws_vpc.this.id
cidr_block = each.value
availability_zone = element(var.azs, index(var.public_subnets, each.value))
map_public_ip_on_launch = true
tags = merge({ Name = "${var.name}-public-${each.value}" }, var.tags)
}
resource "aws_subnet" "private" {
for_each = toset(var.private_subnets)
vpc_id = aws_vpc.this.id
cidr_block = each.value
availability_zone = element(var.azs, index(var.private_subnets, each.value))
tags = merge({ Name = "${var.name}-private-${each.value}" }, var.tags)
}
resource "aws_internet_gateway" "this" {
vpc_id = aws_vpc.this.id
tags = merge({ Name = var.name }, var.tags)
}
resource "aws_route_table" "public" {
vpc_id = aws_vpc.this.id
route {
cidr_block = "0.0.0.0/0"
gateway_id = aws_internet_gateway.this.id
}
tags = merge({ Name = "${var.name}-public" }, var.tags)
}
resource "aws_route_table_association" "public" {
for_each = aws_subnet.public
subnet_id = each.value.id
route_table_id = aws_route_table.public.id
}
resource "aws_eip" "nat" {
domain = "vpc"
tags = merge({ Name = "${var.name}-nat" }, var.tags)
}
resource "aws_nat_gateway" "this" {
allocation_id = aws_eip.nat.id
subnet_id = values(aws_subnet.public)[0].id
tags = merge({ Name = "${var.name}-nat" }, var.tags)
}
resource "aws_route_table" "private" {
vpc_id = aws_vpc.this.id
route {
cidr_block = "0.0.0.0/0"
nat_gateway_id = aws_nat_gateway.this.id
}
tags = merge({ Name = "${var.name}-private" }, var.tags)
}
resource "aws_route_table_association" "private" {
for_each = aws_subnet.private
subnet_id = each.value.id
route_table_id = aws_route_table.private.id
}
Vale la pena notar dos decisiones de diseño. for_each = toset(var.public_subnets) direcciona cada subnet por su CIDR (aws_subnet.public["10.0.1.0/24"]) en lugar de por posición — quitar un CIDR del medio de la lista ya no obliga a Terraform a destruir y recrear todas las subnets siguientes, que es el fallo clásico de count sobre listas. Y la route table privada dirige 0.0.0.0/0 por el NAT gateway; sin eso, las subnets privadas se crean pero quedan aisladas, que es el bug más común de “el módulo funcionó pero nada alcanza internet”.
variables.tf
variables.tf es la API pública del módulo. Cada variable lleva description — aparece en la documentación generada — y type. Usa bloques validation para restricciones que Terraform pueda comprobar en el plan:
variable "name" {
description = "Prefijo de nombre para todos los recursos"
type = string
}
variable "cidr_block" {
description = "Bloque CIDR de la VPC"
type = string
default = "10.0.0.0/16"
validation {
condition = can(cidrhost(var.cidr_block, 0))
error_message = "cidr_block debe ser un CIDR IPv4 válido, p. ej. 10.0.0.0/16."
}
}
variable "azs" {
description = "Zonas de disponibilidad, emparejadas con subnets por posición en la lista. Si se omite, usa las tres primeras AZs de la región."
type = list(string)
default = []
validation {
condition = length(var.azs) == 0 || length(var.azs) >= max(length(var.public_subnets), length(var.private_subnets))
error_message = "Pasa al menos tantas AZs como la lista de subnets más larga, o deja vacío para usar las de la región."
}
}
variable "public_subnets" {
description = "Bloques CIDR de subnets públicas"
type = list(string)
default = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
}
variable "private_subnets" {
description = "Bloques CIDR de subnets privadas"
type = list(string)
default = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
}
variable "enable_dns_support" {
description = "Habilitar soporte DNS en la VPC"
type = bool
default = true
}
variable "enable_dns_hostnames" {
description = "Habilitar DNS hostnames en la VPC"
type = bool
default = true
}
variable "tags" {
description = "Etiquetas adicionales aplicadas a cada recurso"
type = map(string)
default = {}
}
Tres hábitos de diseño de inputs rinden frutos después. Primero, los defaults deberían hacer que module "x" { name = "foo" } funcione — un módulo que necesita quince argumentos para producir algo es un módulo que nadie reutiliza. Segundo, marca los secretos como sensitive = true (p. ej. un db_password) para que Terraform los mantenga fuera del plan; el mismo flag existe en outputs. Tercero, prefiere validation con un error_message claro antes que documentar reglas en prosa — el mensaje es lo que el consumidor ve cuando se equivoca.
outputs.tf
Los outputs son el lado de lectura del contrato. Expón los IDs y atributos que los consumidores van a referenciar — no exportes cosas “por si acaso”, porque cada output es superficie pública que tienes que mantener estable entre versiones:
output "vpc_id" {
description = "ID de la VPC"
value = aws_vpc.this.id
}
output "vpc_cidr_block" {
description = "Bloque CIDR de la VPC"
value = aws_vpc.this.cidr_block
}
output "public_subnet_ids" {
description = "IDs de las subnets públicas, por CIDR"
value = local.public_subnet_ids
}
output "private_subnet_ids" {
description = "IDs de las subnets privadas, por CIDR"
value = local.private_subnet_ids
}
output "nat_gateway_ip" {
description = "IP pública del NAT gateway (para listas de permitidos)"
value = aws_eip.nat.public_ip
}
versions.tf
versions.tf fija el piso que el módulo exige. required_version protege a los consumidores de aplicar en silencio con un Terraform demasiado viejo para la sintaxis usada; los constraints de provider con ~> aceptan releases de parche pero no mayores rompedores:
terraform {
required_version = ">= 1.5.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}
README.md
El README es la primera parada del consumidor, y el registry lo renderiza como página de documentación del módulo. Mínimo indispensable: una línea de propósito, un bloque de uso ejecutable y tablas de inputs/outputs. La mayoría de equipos genera esas tablas con terraform-docs en vez de mantenerlas a mano — lee variables.tf y outputs.tf directamente, así que la documentación no puede divergir del código.
Fuentes de módulos
El argumento source decide de dónde descarga Terraform el módulo, y cada fuente se fija de forma distinta — confundirlas es una respuesta de FAQ mal dada muy común:
| Fuente | Valor de source | Fijación de versión |
|---|---|---|
| Ruta local | "../vpc" o "./modules/vpc" | Ninguna — siempre la copia de trabajo |
| Terraform Registry | "terraform-aws-modules/vpc/aws" | argumento version = "~> 5.0" |
| Git | "git::https://github.com/org/modules.git//vpc" | sufijo ?ref= (tag, rama, SHA) |
Las rutas locales son para desarrollo y para módulos específicos de una app que viven junto a la configuración raíz — no necesitan versionado porque viajan con quien los llama. Las fuentes git sirven para módulos privados entre equipos; fija siempre ?ref= a un tag o SHA de commit, nunca a main, o tu “v1.2.0” pasa a ser en silencio lo último mergeado anoche. El Registry público es para módulos compartidos y documentados — se consume con source + version, sin fontanería de URLs. Además aloja los caballos de batalla de la comunidad (terraform-aws-modules/*, Azure/avm/*, GoogleCloudPlatform/*), que conviene probar antes de escribir tu equivalente.
# Registry — fijado por el argumento version
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.0"
}
# Git — fijado por el sufijo ref (tag o SHA de commit)
module "vpc" {
source = "git::https://github.com/example-org/terraform-modules.git//vpc?ref=v1.2.0"
}
(La organización de GitHub es un placeholder — sustituye tu propio repositorio de módulos.)
terraform init cachea los módulos descargados bajo .terraform/modules y registra las versiones exactas en .terraform.lock.hcl. Commitea el lock file — es lo que hace verificable “la misma versión del módulo en mi laptop y en CI”. Para subir un módulo fijado, cambia el ref/version y ejecuta terraform init -upgrade.
Organizar los repositorios de módulos
Dominan dos estructuras, y la elección importa más que el código de dentro.
Un repo por módulo — exigido por el registry público, que mapea org/name/provider a un solo repositorio llamado terraform-<PROVIDER>-<NAME> y corta versiones a partir de sus releases. Mejor para módulos maduros publicados a muchos consumidores: versionado independiente, CI independiente, release notes limpias.
Un monorepo terraform-modules — un repositorio, un directorio por módulo, consumido vía git::...//vpc?ref=v1.2.0. Mejor para módulos internos de un equipo mientras aún cambian: una PR puede tocar un módulo y sus consumidores, y el descubrimiento es un ls de distancia. El coste es un versionado más grueso — un tag v1.2.0 a nivel repo versiona todos los módulos que contiene, incluso los que no cambiaron — así que la mayoría o acepta eso, o tagea por directorio (vpc/v1.2.0) y fija ?ref=vpc/v1.2.0, que funciona pero confunde a herramientas que esperan tags planos.
La trayectoria habitual: monorepo mientras la API del módulo se asienta, split a repos por módulo cuando equipos externos empiezan a fijarlo.
Consumir un módulo
Llamar al módulo de VPC es solo un bloque module con etiqueta y argumentos:
module "vpc" {
source = "git::https://github.com/example-org/terraform-modules.git//vpc?ref=v1.2.0"
name = "production-vpc"
cidr_block = "10.10.0.0/16"
azs = ["us-east-1a", "us-east-1b"]
public_subnets = ["10.10.1.0/24", "10.10.2.0/24"]
private_subnets = ["10.10.101.0/24", "10.10.102.0/24"]
tags = {
Environment = "production"
Team = "platform"
}
}
module "eks" {
source = "git::https://github.com/example-org/terraform-modules.git//eks?ref=v1.2.0"
name = "production-cluster"
vpc_id = module.vpc.vpc_id
subnet_ids = module.vpc.private_subnet_ids
cluster_version = "1.31"
}
Las referencias a module.vpc.vpc_id son cómo los módulos se pasan datos entre sí — el consumidor nunca toca los recursos de debajo. terraform init descarga cada módulo declarado en .terraform/modules, por eso repites init tras cambiar un source o ref.
Refactorizar recursos existentes en un módulo
El punto de partida honesto de la mayoría de módulos no es un greenfield — es un main.tf funcionando que alguien quiere reutilizar. Terraform tiene un camino limpio para eso, y no pasa por state mv a mano.
Supón que tu config raíz ya gestiona aws_vpc.this, aws_subnet.public y demás directamente. Moverlos dentro de module.vpc son dos ediciones: envolver los bloques de recursos en el directorio del módulo, y luego declarar el cambio de identidad en la raíz:
module "vpc" {
source = "./modules/vpc"
name = "production-vpc"
cidr_block = "10.10.0.0/16"
}
moved {
from = aws_vpc.this
to = module.vpc.aws_vpc.this
}
moved {
from = aws_subnet.public
to = module.vpc.aws_subnet.public
}
Un bloque moved registra “el recurso en esta dirección es el mismo objeto ahora en esa otra”. En el siguiente plan, Terraform actualiza las direcciones en el estado y reporta cero creaciones y cero destrucciones — la VPC viva sobrevive intacta al refactor. Añade un moved por bloque de recurso; los bloques con count o for_each se mueven enteros, ya que cada instancia comparte el mismo par origen/destino.
Los prerrequisitos que lo hacen indoloro: los nombres de recurso del módulo deben coincidir con los originales (aws_vpc.this, no aws_vpc.vpc), y las variables deben mapear para que la config producida sea idéntica — cualquier desviación aparece como destroy/create en el plan, que es justo la señal de parar y corregir el mapeo antes de aplicar.
Componer módulos
Los módulos que llaman a otros módulos — un “landing zone” que conecta VPC + security groups + EKS — son donde la composición paga. Pasa outputs como inputs, y declara orden solo donde Terraform no pueda inferirlo:
# modules/landing-zone/main.tf
module "vpc" {
source = "../vpc"
name = "${var.name}-vpc"
cidr_block = var.vpc_cidr
azs = var.azs
tags = var.tags
}
module "security_groups" {
source = "../security-groups"
vpc_id = module.vpc.vpc_id
name = var.name
tags = var.tags
}
module "eks" {
source = "../eks"
name = "${var.name}-cluster"
vpc_id = module.vpc.vpc_id
subnet_ids = module.vpc.private_subnet_ids
cluster_version = var.kubernetes_version
node_groups = var.node_groups
tags = var.tags
depends_on = [module.security_groups]
}
La mayoría de dependencias son implícitas — module.vpc.vpc_id ya le dice a Terraform que el módulo EKS espera a la VPC. Recurre a depends_on explícito solo cuando no fluyen datos entre módulos pero el orden sí importa (aquí los security groups deberían existir antes de que se registren los nodos, y nada en eks los referencia directamente). Abusar de depends_on congela el grafo de dependencias y serializa applies que podrían correr en paralelo, así que trata cada uno como un code smell que tienes que justificar.
Una advertencia de composición: Terraform 1.x no permite usar count ni for_each en una llamada a módulo basándote en outputs de otro módulo en tiempo de plan — las claves deben conocerse antes del apply. Si necesitas “una instancia de módulo por elemento de una lista producida en otro sitio”, genera la lista en la config raíz, no en un output de módulo.
Probar módulos
Los módulos merecen la misma disciplina de pruebas que el código de aplicación, a dos niveles distintos. Las pruebas de contrato responden “¿cumple el módulo su API” — dadas estas variables, ¿produce estos recursos y outputs? Las pruebas de integración responden “¿converge en el mundo real” — plan, apply, verificación contra el provider en vivo, destroy. La mayoría de módulos necesita lo primero en cada commit y lo segundo antes de cada release.
terraform test nativo (Terraform 1.6+) ejecuta archivos .tftest.hcl contra un plan o apply real — sin herramientas extra, y es lo primero a lo que echar mano:
# modules/vpc/tests/vpc.tftest.hcl
run "vpc_plan" {
command = plan
variables {
name = "test-vpc"
cidr_block = "10.99.0.0/16"
public_subnets = ["10.99.1.0/24", "10.99.2.0/24"]
private_subnets = ["10.99.101.0/24"]
}
assert {
condition = aws_vpc.this.cidr_block == "10.99.0.0/16"
error_message = "El CIDR de la VPC no coincide con el input."
}
assert {
condition = length(aws_subnet.public) == 2
error_message = "Se esperaban 2 subnets públicas."
}
}
command = plan hace la prueba gratis y rápida — aserta sobre el plan sin tocar AWS. Cámbialo por apply (con un run de teardown o una cuenta desechable) cuando necesites IDs de recursos reales. Conecta terraform test al CI junto a fmt -check y validate y la mayoría de regresiones muere en la pull request; esas mismas comprobaciones sirven como la mitad de revisión de diff de una revisión de IaC.
Terratest (Gruntwork, Go) es para comprobaciones end-to-end: despliega de verdad el directorio examples/ y luego aserta sobre outputs en vivo — útil cuando hay que demostrar que el conjunto converge:
package test
import (
"testing"
"github.com/gruntwork-io/terratest/modules/terraform"
"github.com/stretchr/testify/assert"
)
func TestVpcModule(t *testing.T) {
terraformOptions := &terraform.Options{
TerraformDir: "../examples/basic",
Vars: map[string]interface{}{
"name": "terratest-vpc",
"cidr_block": "10.99.0.0/16",
},
}
defer terraform.Destroy(t, terraformOptions)
terraform.InitAndApply(t, terraformOptions)
vpcID := terraform.Output(t, terraformOptions, "vpc_id")
assert.NotEmpty(t, vpcID)
publicSubnets := terraform.OutputList(t, terraformOptions, "public_subnet_ids")
assert.Len(t, publicSubnets, 3)
}
El patrón importa más que el framework: cada módulo trae un examples/basic que cualquiera puede terraform apply, y la suite de pruebas ejercita exactamente ese ejemplo. Si el ejemplo funciona, el módulo funciona.
En CI el pipeline es corto y barato: terraform fmt -check -recursive, terraform validate, terraform test, y un plan sobre examples/basic. Las ejecuciones de Terratest suelen gatear releases en lugar de pull requests — los applies reales en la nube son lentos y cuestan dinero, así que pertenecen al merge a main o al tag, no a cada push.
Versionado y publicación
Los módulos consumidos vía ?ref= de git o el registry necesitan disciplina semver, porque un “cambio pequeño” es un cambio rompedor para quien te fijó:
| Bump | Cuándo | Ejemplo |
|---|---|---|
Mayor (2.0.0) | Quitar o renombrar una variable u output, cambiar un default que recrea recursos | public_subnets → public_subnet_cidrs |
Menor (1.1.0) | Nueva variable opcional, nuevo output, nuevo recurso opcional | Añadir flow_logs_enabled con default |
Parche (1.0.1) | Refactor interno con plan idéntico | Renombrar un valor de locals |
Los tags transportan las versiones para módulos por git:
git tag v1.0.0 -m "Release inicial"
git tag v1.1.0 -m "Soporte de NAT gateway"
git tag v2.0.0 -m "Breaking: rename public_subnets to public_subnet_cidrs"
git push origin --tags
Para publicar en el Terraform Registry público, el módulo necesita su propio repositorio llamado terraform-<PROVIDER>-<NAME> (p. ej. terraform-aws-vpc), la estructura estándar de arriba, y una release de GitHub por versión — el registry recoge las nuevas versiones automáticamente de los releases una vez que inicias sesión con GitHub y seleccionas el repo. terraform init entonces resuelve source = "you/vpc/aws" + version como cualquier otro módulo. Los registries privados (HCP Terraform, self-hosted) siguen el mismo contrato, así que los módulos internos de la organización obtienen la misma ergonomía de source/version que los públicos — que es la razón para graduar un módulo interno maduro fuera del pinning por git.
Detectar un cambio rompedor antes de tagear es la mitad infravalorada del versionado. La comprobación práctica: ejecuta terraform plan dentro de examples/basic contra la release propuesta. Si el plan destruye o reemplaza algo para un consumidor que no cambió nada, eso es un bump mayor — independientemente de lo pequeño que parezca el diff. Mantén un CHANGELOG.md junto al README; los consumidores que deciden si un bump es seguro leen ese archivo, no tu log de commits.
Lo que funciona
- Un módulo por tipo de recurso. Un módulo de VPC, uno de EKS, uno de RDS. Los mega-módulos que toman cincuenta variables y provisionan “todo el entorno” se convierten en el mismo monolito que los módulos debían matar — compón pequeños en su lugar.
for_eachsobrecountpara cualquier cosa respaldada por listas. Los índices posicionales convierten quitar un elemento del medio en un destroy/recreate de todos los posteriores. Las claves hacen las direcciones estables — el mismo razonamiento que Terraform Best Practices aplica a la cirugía de estado.- Defaults que funcionan. Los mejores módulos corren con un solo argumento obligatorio. Los defaults sensatos son documentación que se ejecuta.
validationcon unerror_messagede verdad. “Debe ser un CIDR IPv4 válido, p. ej. 10.0.0.0/16” ahorra un ciclo de depuración; “inválido” no ahorra nada.localspara el ruido computado. Merges de etiquetas, nombres derivados, mapas filtrados — quemain.tfse lea como una lista de recursos, no como un motor de expresiones.- Un directorio
examples/por módulo. Es documentación y objetivo de Terratest a la vez, y te obliga a experimentar tu propio módulo como consumidor. - Etiquetas con
merge({Name = ...}, var.tags). Primero las del módulo, luego las del llamador — para que el consumidor pueda extenderlas o sobreescribirlas sin hacer fork. terraform fmtyterraform validateen CI, antes de que alguien revise estilo HCL a ojo.
Errores comunes
- Hardcodear lo que debería ser variable. El primer tamaño de instancia o región hardcodeada convierte el módulo en una copia renombrada, no en una abstracción.
- Variables para todo. El fallo opuesto: exponer cada argumento de recurso como input significa que el módulo no posee ninguna decisión. Defaults sensatos más una superficie pequeña es la meta.
countsobre listas. Quitar el elemento 1 de 3 desplaza los índices 2 y 3, así que Terraform planea destruirlos y recrearlos. Usafor_eachcon claves estables.- Sin
required_version. Un módulo escrito contra sintaxis 1.5 falla con errores de parseo crípticos en un CLI 1.0 en lugar de un “actualiza Terraform” limpio. - Sin outputs. Los consumidores no pueden referenciar lo que no exportas, así que hardcodean IDs — y el contrato del módulo se rompe.
- Versiones de provider
latest. Un provider sin fijar se actualiza cuando quiere, no cuando quieres.~> 5.0toma parches, salta mayores. depends_oncomo decoración. Si los datos ya fluyen módulo → módulo, el orden explícito solo añade applies serializados.- Fijar un módulo de registry con
?ref=.?ref=es sintaxis de fuentes git; los módulos de registry se fijan conversion = "x.y.z". Mezclarlos da un módulo que falla eninito ignora tu fijación.
Lectura adicional
Preguntas frecuentes
¿Debo usar el Terraform Registry o repos Git privados?
Registry para módulos de los que otros pueden beneficiarse — te da ergonomía de source/version, documentación generada y constraints de versión. Repos Git privados para módulos específicos de la organización hasta que maduren; se fijan con tags o SHAs en ?ref=. Un camino común es git primero, registry cuando la API se estabiliza.
¿Cómo migro un recurso de count a for_each?
Reemplaza count = length(var.x) por for_each = toset(var.x) (las claves pasan a ser los propios valores), cambia las referencias a count.index por each.value, y luego añade un bloque moved por cada índice existente para que Terraform reutilice los recursos vivos en lugar de recrearlos:
moved {
from = aws_subnet.public[0]
to = aws_subnet.public["10.0.1.0/24"]
}
Ojo: no puedes tener versiones count y for_each del mismo bloque resource conviviendo — es un conflicto de declaración. Cambias el bloque y migras el estado con moved, no coexisten.
¿Deben los módulos gestionar su propio estado?
No. Los módulos definen recursos; la configuración raíz que los llama posee el backend de estado. Mantener el estado fuera de los módulos es lo que los hace portables entre backends y entornos.
¿Escribo mi propio módulo de VPC o uso terraform-aws-modules?
Empieza con terraform-aws-modules/vpc — está probado en miles de entornos y te ahorra edge cases que aún no conoces. Escribe el tuyo cuando sus opciones sean aquello contra lo que peleas: políticas de etiquetado inusuales, routing no estándar, o un contrato interno que tu organización impone. El ejemplo de esta guía es deliberadamente mínimo para que se vean las mecánicas; es un andamio de aprendizaje, no un reemplazo de producción.
¿Cómo comparto módulos entre equipos sin un registry?
Las fuentes git con tags ?ref= son el camino de menor fricción — un repo terraform-modules con un directorio por módulo funciona bien. Gradúate a un registry privado (HCP Terraform o self-hosted) cuando necesites constraints de versión, documentación generada o descubribilidad entre muchos equipos.
¿Cómo veo qué creará un módulo antes de usarlo?
Ejecuta terraform plan dentro de su directorio examples/ — el ejemplo instancia el módulo con defaults, así que el plan es el grafo de recursos completo sin necesitar un consumidor. Para inspeccionar valores, terraform console evalúa expresiones como module.vpc.private_subnet_ids interactivamente tras init.
Recursos Relacionados
Infrastructure as Code — Terraform y Pulumi
Guía práctica de infraestructura como código: declarativo vs imperativo, estado, módulos, entornos, testing y un flujo CI/CD seguro.
GuideBuenas Prácticas de Terraform: Módulos, State y Workspaces
Guía práctica de Terraform: módulos, estado remoto, workspaces y seguridad para IaC de producción.
GuideEstrategias de Despliegue: Blue-Green, Canary y Rolling
Guía práctica de estrategias de despliegue: rolling, blue-green, canary, shadow y feature flags. Minimiza el riesgo y el tiempo de rollback al liberar a producción.
RecipeConstruye un Provider Personalizado de Terraform con Python
Extiende Terraform con un provider personalizado usando Python y terraform-plugin-framework para gestionar recursos externos.
DocPlantilla de Revisión de Infrastructure as Code
Una plantilla para revisar código de infraestructura Terraform y CloudFormation.
GuideGuía Completa de Optimización de Costos en AWS
Reduce el gasto en AWS entre un 30 y un 50%: dimensiona EC2, usa instancias Spot, Reserved Instances, Savings Plans, ciclo de vida de S3, RDS y monitoreo.