¿Qué comprueba realmente terraform validate?

terraform validate es un subcomando integrado de Terraform que realiza análisis estático sobre tus archivos de configuración. Lee cada archivo .tf y .tfvars del directorio de trabajo actual (y de forma recursiva los módulos locales), los analiza y comprueba si la configuración es internamente coherente y estructuralmente válida.

Análisis estático, no ejecución

La característica clave de terraform validate es que es totalmente estático. No se hacen conexiones de red, no se llaman API de proveedor y no se lee ningún archivo de estado. La comprobación ocurre por completo en memoria en la máquina que ejecuta el comando. Esto lo hace seguro en cualquier entorno, incluidos los runners de CI sin credenciales de nube, y termina en menos de dos segundos en la mayoría de configuraciones reales.

Esto contrasta con terraform plan, que realiza todas esas comprobaciones estáticas y luego se conecta a las API de proveedor para calcular una diferencia frente a la infraestructura real. Validate es el primer filtro ligero; plan es el filtro completo antes de aplicar. Ejecutar ambos en secuencia te da la cobertura más amplia antes de comprometerte con cualquier cambio de infraestructura.

Los tres modos de funcionamiento

• Modo predeterminado: se ejecuta después de terraform init; comprueba sintaxis, esquema contra los plugins de proveedor descargados y referencias entre archivos
• Sin init: si no existe el directorio .terraform, validate se ejecuta igualmente pero omite las comprobaciones de esquema del proveedor e informa solo de errores de análisis HCL y problemas de referencia que puede resolver sin metadatos del proveedor
• Modo JSON (-json): emite un objeto JSON estructurado con un booleano valid, un entero error_count y un array diagnostics apto para que lo analice el CI y se integre en editores

Entender las tres categorías que cubre terraform validate te ayuda a saber exactamente qué garantiza aprobar la validación y dónde termina esa garantía.

1. Corrección de la sintaxis HCL

La primera pasada analiza cada archivo .tf en busca de sintaxis HCL2 válida. Esto detecta llaves sin cerrar, signos igual ausentes en asignaciones de atributos, definiciones de bloque inválidas, uso incorrecto de la sintaxis heredoc y cualquier otra construcción que no sea HCL válida. Un archivo que falle esta comprobación no puede ser leído por Terraform en absoluto: plan y apply también fallarían. Validate detecta estos errores de inmediato con la ruta del archivo y el número de línea.

2. Conformidad con el esquema del proveedor

Después del análisis, validate comprueba cada bloque de recurso, bloque de fuente de datos y configuración de proveedor contra el esquema definido por el plugin de proveedor correspondiente. Los esquemas especifican qué argumentos son válidos, cuáles son obligatorios y cuáles opcionales, y qué tipo espera cada argumento (string, number, bool, list, map, object). Validate detecta un argumento que no existe para un tipo de recurso, un argumento con el tipo equivocado (por ejemplo, pasar una cadena donde se requiere un número) y un argumento obligatorio que falta por completo.

3. Validez de las referencias internas

La tercera categoría es la comprobación de referencias cruzadas dentro de la configuración. Las configuraciones de Terraform referencian con frecuencia otros recursos, variables, locals, salidas de módulos y fuentes de datos por nombre. Validate comprueba que cada referencia (por ejemplo var.region, local.common_tags, aws_vpc.main.id, module.networking.subnet_ids) apunte a algo declarado realmente en algún lugar de la configuración. Una variable no declarada, un error tipográfico en una referencia a recurso o una salida de módulo inexistente se detectan aquí.

Los límites de terraform validate son tan importantes como lo que cubre. Muchos desarrolladores descubren estos límites cuando una configuración que pasa la validación falla en el momento de aplicar. Cada una de estas categorías requiere terraform plan, pruebas de integración o herramientas de política como tflint o Checkov.

Valores reales de los argumentos de recursos

Validate comprueba que un argumento existe y tiene el tipo correcto, pero no puede comprobar si el valor es válido en el mundo real. Un recurso aws_instance puede tener un argumento ami que sea una cadena (correcto en tipo), pero validate no tiene forma de saber si ese AMI ID concreto existe en tu cuenta o región de AWS. Un AMI inválido, un ID de grupo de seguridad inexistente o un nombre de zona de disponibilidad incorrecto pasarán validate y solo fallarán en plan o apply.

Archivo de estado e infraestructura existente

Validate nunca lee tu archivo de estado de Terraform. No puede detectar que un recurso que estás definiendo entra en conflicto con otro que ya existe, que un recurso se eliminó fuera de Terraform (desviación del estado) o que un cambio previsto infringe una restricción que solo se puede evaluar contra la infraestructura real actual. Todo eso son cuestiones de las fases de plan y apply.

Expresiones dinámicas que dependen de fuentes de datos

Las expresiones count, for_each y condicionales son HCL válido y validate las analiza sin problema. Pero si sus valores dependen de una fuente de datos (por ejemplo for_each = toset(data.aws_availability_zones.available.names)), la expresión no se puede evaluar por completo en el momento de validar porque la fuente de datos no se ha consultado. Validate confirma que la sintaxis de la expresión es correcta; no puede confirmar el resultado en tiempo de ejecución.

Autenticación y permisos del proveedor

Validate no hace ninguna llamada a API. No detectará que tus credenciales de AWS han caducado, que a tu cuenta de servicio le faltan los permisos IAM necesarios ni que tu configuración de proveedor apunta a la región o el proyecto equivocados. Todos los errores de autenticación solo aparecen en la fase de plan o apply, cuando el cliente del proveedor se inicializa de verdad y se hacen las llamadas.

Políticas de seguridad y reglas de cumplimiento

Validate no tiene noción de política de seguridad. Un bucket de S3 configurado como público, una instancia de EC2 sin cifrado o un grupo de seguridad con entrada 0.0.0.0/0 en el puerto 22 pasarán validate sin ninguna advertencia. Las comprobaciones de seguridad y cumplimiento requieren herramientas de política dedicadas como Checkov, tfsec o HashiCorp Sentinel.

La fuente más frecuente de confusión sobre terraform validate es en qué se diferencia de terraform plan. Se solapan mucho, pero operan en niveles distintos, y ambos son necesarios para un flujo completo antes de aplicar.

terraform validate comprueba si una configuración es sintácticamente válida e internamente coherente, con independencia de las variables proporcionadas o del estado existente.

Dónde se solapan

Ambos comandos analizan tus archivos HCL y buscan errores de sintaxis. Ambos comprueban los esquemas de proveedor cuando los plugins de proveedor están disponibles. Ambos validan las referencias internas. Un error de configuración que detecte terraform validate también lo detectaría terraform plan: validate simplemente es más rápido y no requiere credenciales de nube ni un backend de estado.

Hasta dónde llega plan

terraform plan inicializa los clientes de proveedor, se autentica con las API de nube, lee el estado actual y consulta las fuentes de datos. Esto le permite detectar cosas que validate no puede: un valor de argumento que la API del proveedor rechaza, una consulta a fuente de datos que devuelve resultados inesperados, errores de cuota o de límite de peticiones, y conflictos entre la configuración propuesta y la infraestructura existente registrada en el estado.

Ejecutar terraform validate es sencillo, pero los pasos que lo rodean importan para sacarle todo el partido al comando.

# Validación básica
terraform validate

# Salida JSON para que la analice el CI
terraform validate -json

# Ejemplo de estructura de salida JSON
{
  "valid": false,
  "error_count": 2,
  "diagnostics": [
    {
      "severity": "error",
      "summary": "Unsupported argument",
      "detail": "An argument named 'regoin' is not expected here. Did you mean 'region'?",
      "range": {
        "filename": "main.tf",
        "start": { "line": 8, "column": 3 }
      }
    }
  ]
}

terraform validate encaja de forma natural en pipelines de CI porque no necesita credenciales de nube, se ejecuta en segundos y detecta casi todos los errores de autoría antes de que consuman una ejecución de plan o lleguen a una revisión de código. El patrón estándar es ejecutarlo en cada pull request que modifique archivos .tf.

Ejemplo con GitHub Actions

El siguiente flujo de trabajo instala Terraform, ejecuta init con -backend=false para no necesitar credenciales de estado y ejecuta validate. Si validate falla, el flujo de trabajo termina con código distinto de cero y bloquea la fusión del pull request.

name: Terraform Validate

on:
  pull_request:
    paths:
      - '**.tf'
      - '**.tfvars'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: '1.8.0'

      - name: Terraform Init (no backend)
        run: terraform init -backend=false

      - name: Terraform Validate
        run: terraform validate -json | tee validate-output.json
        # Exit code 1 on any error - fails the workflow automatically

Combinar validate con tflint

tflint es un linter que detecta problemas que terraform validate deja pasar: comprobaciones de reglas específicas del proveedor (como tipos de instancia de AWS inválidos), declaraciones sin usar y reglas de política propias. Ejecutar tflint después de validate en el mismo trabajo de CI ofrece una cobertura de análisis estático más amplia. tflint tiene plugins de reglas específicas para AWS, Azure y GCP que comprueban los valores de los argumentos contra opciones válidas conocidas, detectando errores que la comprobación genérica de esquema de validate no puede.

• terraform fmt -check: verifica que el código sigue las convenciones de estilo de Terraform (falla si algún archivo necesita reformateo)
• terraform validate: comprueba sintaxis, conformidad con el esquema y referencias internas
• tflint: reglas específicas del proveedor, detección de variables sin usar y aplicación de políticas propias
• Checkov o tfsec: análisis de políticas de seguridad y cumplimiento
• terraform plan: validación en tiempo de ejecución en un entorno de staging con credenciales reales

terraform validate es una base, no un techo. Un flujo de trabajo maduro con Terraform combina varias técnicas de validación para detectar distintas clases de error en el punto adecuado del ciclo de desarrollo.

Formatea antes de validar

Ejecuta terraform fmt antes de validate en todos los flujos, locales y de CI. El formato canónico de HCL no es solo cuestión de estilo: evita casos límite en los que un espaciado o una ubicación de comentario incoherentes ocultan errores reales en la salida del análisis. El Formateador HCL de Aback Tools ofrece la misma normalización en tu navegador sin necesidad de tener Terraform instalado, algo útil para revisiones rápidas o para editar en máquinas donde no puedes ejecutar terraform fmt.

Ejecuta siempre init antes de validate en CI

Ejecutar validate sin init solo da un análisis parcial: análisis HCL y comprobación de referencias, pero sin validación del esquema del proveedor. Omitir las comprobaciones de esquema significa que puedes fusionar una configuración que usa un nombre de argumento con errata o pasa el tipo equivocado a un atributo de recurso. Los pocos segundos extra que añade init -backend=false al trabajo de CI merecen la pena por la cobertura.

Usa -json para salidas estructuradas en CI

La salida legible predeterminada de validate es clara para depurar en local, pero la salida JSON es mucho más útil en pipelines automatizados. Con -json puedes analizar el array diagnostics para extraer rutas de archivo y números de línea, anotar los diffs del pull request con comentarios de error en línea usando la API de GitHub Checks, o enviar los errores a una notificación personalizada de Slack. Analiza primero el booleano valid: si es true, el array diagnostics puede contener igualmente advertencias que merece la pena mostrar.

Valida todos los módulos de forma independiente

terraform validate en un módulo raíz también comprueba los módulos locales a los que llama, pero los módulos remotos solo se comprueban después de que init los descargue. Para repositorios de módulos, ejecuta validate por separado en cada directorio de módulo durante el desarrollo. Así aparecen los errores de esquema del propio módulo antes de que los consumidores lleguen a referenciarlo.

Mantén los archivos .tf formateados antes de confirmar

Usa un hook de pre-commit que ejecute terraform fmt -check y falle si algún archivo .tf no está en formato canónico. Esto mantiene coherente todo el código, evita diffs solo de estilo en las revisiones y hace que la salida de validate sea más fácil de leer porque el código tiene estructura limpia. Elimina los comentarios de desarrollo de las configuraciones de producción con el Eliminador de comentarios de Terraform HCL para mantener los archivos confirmados limpios y legibles.