Terraform: infraestructura como código para equipos

Terraform, de HashiCorp, es la herramienta de infraestructura como código (IaC) más adoptada del mercado. Permite definir, provisionar y gestionar infraestructura en cualquier proveedor cloud (AWS, Azure, GCP, y cientos más) usando un lenguaje declarativo propio llamado HCL (HashiCorp Configuration Language). La promesa de Terraform es atractiva: infraestructura reproducible, versionada en Git, revisable por el equipo y desplegable de forma automatizada.

Pero Terraform bien usado en un equipo es muy diferente a Terraform usado por una persona en su portátil. Los proyectos de infraestructura crecen en complejidad, los equipos necesitan colaborar sobre el mismo estado, los cambios en producción requieren procesos de aprobación y los módulos que funcionan para una instalación necesitan ser reutilizables para otras. Este artículo aborda Terraform desde la perspectiva de los equipos empresariales: cómo estructurar proyectos que escalen, cómo colaborar de forma segura y cómo integrar Terraform en los pipelines de CI/CD.

También abordaremos las alternativas a Terraform puro, como OpenTofu (el fork open source de Terraform tras el cambio de licencia de HashiCorp), Terragrunt para DRY y orquestación de módulos, y cuándo considerar herramientas como Pulumi o AWS CDK para equipos con preferencias de lenguajes de programación convencionales.

Conceptos fundamentales que todo el equipo debe dominar

Antes de hablar de estructura y organización, es importante que todo el equipo tenga una comprensión clara de los conceptos que diferencian a Terraform de otros enfoques de provisioning.

• Estado (state): Terraform mantiene un archivo de estado que mapea los recursos definidos en el código con los recursos reales en la infraestructura. El estado es la fuente de verdad de Terraform y su gestión es uno de los aspectos más críticos del uso en equipo.
• Plan y Apply: terraform plan genera un plan de ejecución que muestra qué cambios se van a realizar sin ejecutarlos. terraform apply ejecuta esos cambios. En producción, el plan debe ser revisado y aprobado antes de aplicarlo.
• Providers: son los plugins que permiten a Terraform interactuar con las APIs de los diferentes proveedores. Cada proveedor expone recursos y data sources. Los providers se versionan de forma independiente a Terraform.
• Recursos y Data Sources: los recursos (resource) definen infraestructura que Terraform crea y gestiona. Los data sources (data) permiten consultar información de la infraestructura existente sin gestionarla.
• Variables y Outputs: las variables permiten parametrizar la configuración para que el mismo código sea reutilizable con diferentes valores. Los outputs exportan valores del módulo para que otros módulos o configuraciones puedan consumirlos.
• Módulos: son unidades de código Terraform reutilizables. Permiten encapsular la lógica de creación de un componente de infraestructura (una VPC, un clúster de EKS, una base de datos RDS) y reutilizarla con diferentes parámetros.

Gestión del estado remoto: el primer paso para trabajar en equipo

El mayor error que cometen los equipos que empiezan con Terraform es dejar el archivo de estado en el sistema de archivos local o en el repositorio Git. El estado en local hace imposible la colaboración (solo una persona puede aplicar cambios a la vez) y es un riesgo de seguridad (el estado puede contener valores sensibles como contraseñas de bases de datos o claves de API).

La solución es configurar un backend remoto que almacene el estado de forma centralizada, segura y con bloqueo de concurrencia. Los backends más comunes son S3 con DynamoDB para bloqueo (para infraestructura en AWS), Azure Blob Storage con bloqueo nativo, Google Cloud Storage y Terraform Cloud/Enterprise de HashiCorp.

Configuración del backend S3 con bloqueo DynamoDB

Para proyectos que corren en AWS, el patrón estándar es usar S3 para almacenar el archivo de estado con cifrado SSE-KMS y versionado habilitado, y una tabla de DynamoDB para el mecanismo de bloqueo que previene que dos ejecuciones simultáneas corrompan el estado. El bucket S3 debe tener block public access activado, acceso de escritura restringido mediante políticas IAM y acceso de solo lectura para los miembros del equipo que necesiten inspeccionar el estado sin modificarlo.

Una práctica importante es usar un workspace de estado separado por entorno (desarrollo, staging, producción) y, en proyectos grandes, un archivo de estado separado por componente de infraestructura. Un único archivo de estado para toda la infraestructura de producción es un cuello de botella operativo y un riesgo: cualquier operación de Terraform necesita bloquear todo el estado, y un error puede afectar a componentes no relacionados.

Estructura de proyectos: cómo organizar el código para que escale

No existe una única estructura de proyecto Terraform correcta para todos los casos, pero hay principios que se aplican universalmente. El más importante es separar el estado de la infraestructura en múltiples archivos de estado con granularidad apropiada. Una estructura común para proyectos empresariales medianos o grandes organiza el código en capas o componentes independientes.

Estructura por capas (recomendada para la mayoría de proyectos)

• Capa de red (networking): VPCs, subredes, tablas de routing, VPN, DNS. Esta capa es la más estable; los cambios son infrecuentes y tienen alto impacto.
• Capa de identidad y seguridad (security): políticas IAM, roles, grupos de seguridad base, KMS keys, certificados. También es relativamente estable.
• Capa de datos (data): bases de datos RDS, Aurora, ElastiCache, S3 buckets de datos. Cambia con menor frecuencia que la capa de aplicación.
• Capa de aplicación (app o services): instancias EC2, grupos de autoescalado, EKS, ECS, App Service plans, etc. Cambia con mayor frecuencia.
• Módulos compartidos: directorio de módulos internos reutilizables que encapsulan patrones de infraestructura propios de la organización.

Para proyectos multi-entorno, cada capa se replica en una carpeta por entorno. Herramienta como Terragrunt simplifica la gestión de configuraciones multi-entorno evitando la duplicación de la configuración del backend y las invocaciones de módulos entre entornos. Con Terragrunt, la configuración del backend se define una vez y se genera dinámicamente para cada entorno y componente.

Módulos de Terraform: principios de diseño reutilizable

Los módulos son el mecanismo de reutilización de Terraform. Un módulo bien diseñado encapsula la creación de un componente de infraestructura con sus configuraciones de seguridad y buenas prácticas predefinidas, exponiendo solo los parámetros que razonablemente varían entre usos.

El Terraform Registry contiene miles de módulos públicos mantenidos por proveedores cloud y la comunidad. Antes de escribir un módulo propio, vale la pena evaluar los módulos oficiales del Registro. Los módulos de la organización terraform-aws-modules (para AWS), como terraform-aws-vpc, terraform-aws-eks o terraform-aws-rds, están ampliamente adoptados, bien mantenidos y siguen las mejores prácticas. Usarlos como base ahorra tiempo y reduce errores.

Principios para módulos de alta calidad

• Un módulo debe hacer una cosa bien. Evita módulos 'todo en uno' que crean VPC, EKS, RDS y todo lo demás. Separa las responsabilidades.
• Documenta todas las variables con descripción y tipo. Los tipos de Terraform (string, number, bool, list, map, object) ayudan a detectar errores antes del plan.
• Define valores por defecto sensatos para variables opcionales, pero no para variables obligatorias.
• Exporta outputs relevantes para que otros módulos puedan consumir la información del recurso creado.
• Versiona los módulos con Git tags y referencia siempre una versión concreta en las llamadas, nunca main o master.
• Incluye ejemplos de uso en el directorio examples/ del módulo. Son la documentación más útil.
• Escribe tests con Terratest (Go) o con los tests nativos de Terraform (terraform test, disponible desde la versión 1.6). Los tests previenen regresiones al evolucionar los módulos.

Pipelines de CI/CD para Terraform: el ciclo de trabajo en equipo

Integrar Terraform en un pipeline de CI/CD es fundamental para garantizar que los cambios en la infraestructura pasan por los mismos controles que los cambios en el código de la aplicación: revisión por pares, análisis estático, testing y aprobación antes del despliegue en producción.

El flujo de trabajo estándar es el siguiente: en una rama de feature, el pipeline ejecuta terraform fmt para verificar el formato, terraform validate para comprobar la sintaxis y la coherencia, herramientas de análisis estático como tfsec, Checkov o Trivy para detectar configuraciones inseguras, y terraform plan para generar y publicar el plan como comentario en el Pull Request. Cuando el PR es aprobado y se fusiona a la rama principal, el pipeline ejecuta terraform apply sobre el plan previamente generado.

Opciones de plataforma para pipelines de Terraform

• GitHub Actions: la opción más popular para proyectos que ya usan GitHub. La acción hashicorp/setup-terraform facilita la configuración. La integración con OpenID Connect (OIDC) elimina la necesidad de almacenar credenciales de cloud como secrets de GitHub.
• GitLab CI/CD: bien integrado con los proyectos de GitLab, con soporte para entornos y protección de ramas de producción.
• Atlantis: herramienta open source específicamente diseñada para automatizar flujos de trabajo de Terraform en Pull Requests de GitHub, GitLab y Bitbucket. Gestiona el bloqueo, genera el plan en comentarios del PR y aplica al hacer merge.
• Terraform Cloud / HCP Terraform: la plataforma SaaS de HashiCorp para gestionar el estado remoto, las ejecuciones de Terraform y las políticas Sentinel. Simplifica la gestión en equipos grandes y tiene un nivel gratuito para equipos pequeños.
• Spacelift o Env0: plataformas SaaS especializadas en CI/CD para IaC, con soporte para Terraform, OpenTofu, Pulumi y Cloudformation, con funcionalidades avanzadas de gobernanza y gestión de costes.

Gestión de secretos en Terraform: un problema no resuelto por defecto

Terraform tiene un problema estructural con los secretos: algunos valores sensibles (contraseñas de bases de datos, claves de API, tokens) a menudo necesitan pasarse como variables de Terraform o se almacenan en el estado, donde quedan en texto plano. Existen varios enfoques para mitigar este problema.

El enfoque más robusto es evitar que los secretos pasen por Terraform en la medida de lo posible. Por ejemplo, para una contraseña de base de datos RDS, Terraform puede crear el recurso con una contraseña aleatoria generada por el recurso random_password, almacenar esa contraseña en AWS Secrets Manager y que la aplicación la recupere directamente de Secrets Manager en tiempo de ejecución. Terraform gestiona la infraestructura; los secretos fluyen directamente entre los servicios de gestión de secretos y las aplicaciones, sin pasar por el estado de Terraform.

Cuando los secretos deben pasarse a Terraform (por ejemplo, para configurar una integración con un servicio externo que requiere una API key), usa las variables de entorno del sistema para inyectarlos (Terraform lee las variables de entorno con el prefijo TF_VAR_) en lugar de incluirlos en archivos tfvars. Así, los secretos no aparecen en el historial de Git ni en los logs del pipeline.

La infraestructura como código no solo hace la infraestructura más reproducible; la hace auditable, revisable y recuperable. Eso es lo que diferencia la ingeniería de la administración ad-hoc.

Drift detection: cuando la infraestructura real diverge del código

El drift ocurre cuando alguien modifica la infraestructura directamente en la consola del proveedor cloud sin actualizar el código de Terraform. Es uno de los problemas más insidiosos en equipos que usan IaC, porque puede pasar desapercibido hasta que la próxima ejecución de terraform plan genera un plan de cambios inesperados que revierten la modificación manual.

Para detectar el drift proactivamente, se puede ejecutar terraform plan de forma periódica en el pipeline y notificar al equipo si se detectan diferencias. Herramientas como driftctl analizan toda la infraestructura de un proveedor cloud (no solo la que gestiona un específico proyecto Terraform) y detectan recursos que existen en la nube pero no están gestionados por código. La solución correcta al drift siempre es actualizar el código de Terraform para que refleje el estado deseado, nunca ignorar el plan que revierte el cambio manual.

Testing de infraestructura: de análisis estático a tests de integración

La infraestructura como código es código, y como tal debería tener su estrategia de testing. Hay varias capas de testing aplicables a Terraform, con diferente nivel de profundidad y coste de ejecución.

• Formato y sintaxis: terraform fmt -check y terraform validate. Son instantáneos y deben ejecutarse en cada commit.
• Análisis estático de seguridad: tfsec, Checkov o trivy --config para detectar configuraciones inseguras antes de aplicar. Se ejecutan en segundos.
• Tests de unidad de módulos: terraform test (nativo desde 1.6) permite escribir tests que verifican el plan de un módulo con diferentes configuraciones de entrada, sin necesidad de crear infraestructura real.
• Tests de integración con Terratest: el framework de testing de infraestructura de Gruntwork escrito en Go. Crea infraestructura real, verifica que funciona correctamente y la destruye. Son lentos y costosos pero verifican el comportamiento real.
• Tests de conformidad con Open Policy Agent (OPA) o Sentinel: políticas que verifican que la infraestructura cumple con las políticas de seguridad y gobernanza de la organización, como el uso de cifrado en todos los volúmenes o el etiquetado correcto de recursos.

OpenTofu: el fork open source de Terraform

En agosto de 2023, HashiCorp cambió la licencia de Terraform de MPL 2.0 (open source) a BSL 1.1 (Business Source License), que restringe el uso comercial de Terraform en productos competidores. En respuesta, la comunidad creó OpenTofu, un fork de Terraform 1.6 bajo la licencia MPL 2.0, gestionado por la Linux Foundation.

OpenTofu es compatible con Terraform en la mayoría de los casos de uso empresariales. Para organizaciones que necesitan total libertad de uso sin restricciones de licencia, o que tienen preocupaciones sobre la dirección de desarrollo de HashiCorp bajo la propiedad de IBM (que adquirió HashiCorp en 2024), OpenTofu es una alternativa completamente viable. La mayoría de los proveedores de CI/CD y las herramientas del ecosistema (Atlantis, Terragrunt, Spacelift) ya soportan OpenTofu como alternativa a Terraform.

Errores comunes en proyectos Terraform de equipos

• Estado en local o en Git: el error más grave, que hace imposible la colaboración y expone secretos.
• Un único archivo de estado para toda la infraestructura: crea un cuello de botella y maximiza el radio de impacto de los errores.
• No versionar los módulos externos: usar source = git::... sin un tag de versión puede romper deployments cuando el módulo cambia.
• Aplicar terraform apply directamente en producción sin revisión del plan: cualquier error en el código puede destruir infraestructura crítica.
• No tener protección de estado de recursos críticos con lifecycle { prevent_destroy = true }: protege recursos como bases de datos de producción de ser eliminados accidentalmente.
• Dejar secrets en archivos tfvars versionados en Git.
• No gestionar el drift: la infraestructura real diverge del código y nadie lo sabe.
• Módulos demasiado grandes que crean demasiados recursos: dificultan la comprensión, el testing y la reutilización.

Conclusión: Terraform como práctica de equipo

Terraform es una herramienta poderosa que puede transformar la forma en que un equipo gestiona la infraestructura cloud, pero su valor real se realiza cuando se adopta como una disciplina de equipo, no como una herramienta individual. El backend de estado remoto, los pipelines de CI/CD con revisión de planes, la estructuración de módulos reutilizables y las políticas de prevención de drift son los elementos que diferencian un uso maduro de Terraform de uno improvisado.

Si estás comenzando con Terraform en tu empresa, el camino más pragmático es: primero, configura el backend remoto (S3 + DynamoDB para AWS, Blob Storage para Azure o GCS para GCP). Segundo, establece el flujo de trabajo de CI/CD básico con plan en PR y apply en merge. Tercero, empieza a modularizar el código de infraestructura que se repite entre entornos. Con esa base operacional en su lugar, el equipo puede crecer en complejidad de forma controlada y sostenible.