¿Qué son HCL y HOCON? Lenguajes de configuración explicados

HCL significa HashiCorp Configuration Language. Es un lenguaje de configuración de dominio específico creado por HashiCorp en 2014, inicialmente para dar soporte a Terraform. Los archivos HCL usan la extensión `.hcl` (o `.tf` específicamente para Terraform) y están diseñados para ser legibles por humanos, analizables por máquinas y compatibles con JSON: todo documento JSON válido también es HCL válido.

HCL no es un lenguaje de programación. No puede hacer cálculos, definir funciones ni controlar el flujo del programa como Python o JavaScript. Es un lenguaje de configuración declarativo: describes el estado deseado de la infraestructura y la herramienta que lee el HCL (Terraform, Packer, Vault, Consul, Nomad) decide cómo alcanzarlo. Esta restricción es intencionada: hace que las configuraciones HCL sean predecibles y auditables.

Fundamentos de la sintaxis HCL

HCL usa una estructura de bloques con atributos, bloques anidados y expresiones. Los atributos son pares clave-valor; los bloques agrupan atributos relacionados y pueden anidarse. Los comentarios usan `#` o `//` para una línea y `/* */` para varias.

# Comentario de una línea
resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

  tags = {
    Name        = "web-server"
    Environment = "production"
  }

  # Bloque anidado
  root_block_device {
    volume_size = 20
    encrypted   = true
  }
}

Dónde se usa HCL

• Terraform: el principal consumidor de HCL; cada archivo `.tf` es HCL que describe infraestructura en la nube y local.
• Packer: HCL2 (la versión 2 del lenguaje) se usa para definir compilaciones de imágenes de máquina para AMI de AWS, imágenes de GCP y otras.
• Vault: HCL se usa en archivos de políticas que definen reglas de control de acceso en HashiCorp Vault.
• Consul: los archivos de configuración de la malla de servicios, las comprobaciones de estado y las definiciones de servicio usan HCL.
• Nomad: las especificaciones de trabajos de orquestación de cargas se escriben en HCL.

HOCON significa Human-Optimized Config Object Notation. Lo creó Typesafe (hoy Lightbend) en 2011 como formato de configuración de la librería Typesafe Config, que impulsa Akka, Play Framework, Lagom y otros frameworks basados en la JVM. Los archivos HOCON usan la extensión `.conf` y son un superconjunto estricto de JSON: todo archivo JSON válido es HOCON válido.

HOCON está pensado para la configuración en tiempo de ejecución de aplicaciones, no para definir infraestructura. Su función destacada son las sustituciones: la capacidad de referenciar otros valores de configuración dentro del mismo archivo mediante la sintaxis de sustitución, referenciando por ruta otros valores de configuración o variables de entorno. Esto hace que HOCON sea especialmente adecuado para configuración por capas: un archivo base puede definir valores por defecto y un archivo específico por entorno puede sobrescribir valores concretos, con sustituciones que toman datos de variables de entorno u otras fuentes.

Fundamentos de la sintaxis HOCON

# Configuración de la aplicación
app {
  name = "my-service"
  version = "1.0.0"

  server {
    host = "0.0.0.0"
    port = 8080
    # Sustitución desde una variable de entorno
    port = ${?APP_PORT}
  }

  database {
    url = "jdbc:postgresql://localhost:5432/mydb"
    # Sustitución desde otro valor de configuración
    connection-pool = ${app.server.port}
  }
}

# Listas
allowed-origins = ["https://example.com", "https://api.example.com"]

Funciones de HOCON que van más allá de JSON

• Comentarios: comentarios de una línea con `#` y `//`; JSON no admite comentarios.
• Sustituciones: `${path.to.value}` referencia otras claves; `${?ENV_VAR}` no falla si la variable no está definida.
• Directivas include: include "other.conf" fusiona archivos de configuración externos al analizar.
• Fusión de objetos: las claves duplicadas fusionan sus valores en vez de sobrescribirlos; permite configuración por capas.
• Flexibilidad clave-valor: admite key = value, key : value y key value (separado por espacio) de forma equivalente.
• Cadenas sin comillas: los valores de cadena simples no necesitan comillas salvo que contengan caracteres especiales.

HCL y HOCON resuelven problemas parecidos desde ángulos distintos. Ambos son más legibles que JSON para configuraciones complejas, ambos admiten comentarios y ambos tienen una capa de compatibilidad con JSON. Pero sus objetivos de diseño, sus casos de uso principales y sus integraciones de ecosistema son tan distintos que rara vez eliges entre ellos: la herramienta que usas decide por ti.

HCL describe qué infraestructura debe existir. HOCON describe cómo debe comportarse una aplicación. La diferencia de propósito moldea cada decisión de diseño en ambos lenguajes.

La diferencia conceptual clave

HCL es imperativo en cuanto a la estructura: los bloques tienen tipos y etiquetas (`resource "aws_instance" "web"`) que llevan un significado semántico interpretado por la herramienta. Estás declarando entidades de un tipo concreto con ciertas propiedades. HOCON es puramente un formato de datos: define una estructura jerárquica clave-valor que las aplicaciones leen al arrancar. No tiene concepto de bloques con tipo; todo es una clave que apunta a un valor, un objeto o una lista.

Los archivos HCL se editan sobre todo como parte de un proyecto de Terraform, aunque los mismos principios se aplican a Packer, Vault y Nomad. Acertar con el formato y la estructura importa porque las herramientas de HashiCorp validan HCL de forma estricta en la fase plan o validate, y los bloques HCL mal formados producen errores difíciles de rastrear si el archivo no está bien indentado.

Los archivos de configuración HOCON en proyectos JVM suelen estar en `src/main/resources/application.conf`. Las aplicaciones Akka usan HOCON para la configuración del sistema de actores, los ajustes de dispatcher y la configuración de extensiones. Play Framework lo usa para rutas, conexiones de base de datos y ajustes de la aplicación. El formato es permisivo (cadenas sin comillas, operadores de asignación flexibles, comentarios), pero un formato sensible al espaciado hace que los archivos sean más fáciles de leer y mantener.

Formatear archivos HOCON

El Formateador HOCON de Aback Tools formatea archivos de configuración HOCON con sangría coherente de 4 espacios, espaciado correcto de clave-valor, manejo limpio de sustituciones y las convenciones de Typesafe Config. Resulta especialmente útil al editar archivos grandes de Akka o Play que han acumulado formatos incoherentes por culpa de varios colaboradores.

Convertir HOCON a YAML

Cuando una herramienta de tu pipeline espera YAML pero la configuración de tu aplicación es HOCON, el Conversor de HOCON a YAML traduce la estructura clave-valor de HOCON a su equivalente en YAML. Ten en cuenta que las funciones propias de HOCON (sustituciones, directivas include y claves fusionadas) se resuelven antes de la conversión, así que la salida YAML refleja la configuración final fusionada y no la sintaxis cruda de la plantilla HOCON.

HCL y HOCON conviven con un panorama más amplio de formatos de configuración. Elegir el adecuado rara vez es una decisión libre: las herramientas que usas dictan el formato. Pero entender dónde encaja cada uno ayuda a razonar sobre la portabilidad de la configuración y las ventajas e inconvenientes de cada herramienta.

Comparativa de los principales formatos de configuración

HCL y YAML juntos en flujos de trabajo con Terraform

En la práctica, un proyecto de Terraform usa HCL para todas las definiciones de infraestructura, mientras que el pipeline de CI/CD que ejecuta Terraform suele configurarse en YAML (GitHub Actions, GitLab CI, CircleCI). Conviven sin conflicto: HCL es la entrada de Terraform y YAML la del pipeline. Si trabajas con ambos, se aplica la misma disciplina de formato. Para errores de YAML en tus archivos de CI, el flujo de Cómo detectar y corregir errores de YAML se aplica directamente.

HOCON, TOML y YAML para la configuración de aplicaciones

Para aplicaciones que no son JVM, TOML y YAML son opciones más comunes que HOCON. TOML es el estándar de Rust (Cargo.toml), del empaquetado de Python (pyproject.toml) y de los sitios estáticos con Hugo. YAML domina Kubernetes, Ansible, Docker Compose y la mayoría de las herramientas cloud native. HOCON es la elección correcta específicamente cuando tu entorno de ejecución es un framework JVM que incluye Typesafe Config: obtienes las funciones de HOCON gratis, y pelearte con el framework para usar otro formato crea más problemas de los que resuelve.

Artículos relacionados sobre formatos

Si estás evaluando formatos de configuración para un proyecto nuevo, los artículos complementarios de esta serie cubren las alternativas más cercanas. Cómo crear un archivo INI cubre el formato de configuración más simple. Cómo comentar en YAML correctamente trata los detalles de la sintaxis de YAML. Y ¿Qué comprueba realmente terraform validate? cubre cómo aparecen los errores de HCL en un flujo de trabajo con Terraform.