O que são HCL e HOCON? Linguagens de configuração explicadas

HCL significa HashiCorp Configuration Language. É uma linguagem de configuração específica de domínio criada pela HashiCorp em 2014, inicialmente para dar suporte ao Terraform. Os arquivos HCL usam a extensão `.hcl` (ou `.tf` especificamente para Terraform) e foram projetados para serem legíveis por humanos, analisáveis por máquinas e compatíveis com JSON: todo documento JSON válido também é HCL válido.

HCL não é uma linguagem de programação. Ele não executa cálculos, não define funções nem controla o fluxo do programa como Python ou JavaScript. É uma linguagem de configuração declarativa: você descreve o estado desejado da infraestrutura e a ferramenta que lê o HCL (Terraform, Packer, Vault, Consul, Nomad) decide como alcançá-lo. Essa restrição é intencional: torna as configurações HCL previsíveis e auditáveis.

Fundamentos da sintaxe HCL

HCL usa uma estrutura em blocos com atributos, blocos aninhados e expressões. Os atributos são pares chave-valor; os blocos agrupam atributos relacionados e podem ser aninhados. Os comentários usam `#` ou `//` em uma linha e `/* */` em várias.

# Comentário de uma linha
resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

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

  # Bloco aninhado
  root_block_device {
    volume_size = 20
    encrypted   = true
  }
}

Onde o HCL é usado

• Terraform: o principal consumidor de HCL; cada arquivo `.tf` é HCL que descreve infraestrutura na nuvem e on-premises.
• Packer: o HCL2 (a versão 2 da linguagem) é usado para definir builds de imagens de máquina para AMIs da AWS, imagens do GCP e outras.
• Vault: o HCL é usado em arquivos de política que definem regras de controle de acesso no HashiCorp Vault.
• Consul: arquivos de configuração da malha de serviços, verificações de saúde e definições de serviço usam HCL.
• Nomad: as especificações de job de orquestração de cargas são escritas em HCL.

HOCON significa Human-Optimized Config Object Notation. Foi criado pela Typesafe (hoje Lightbend) em 2011 como formato de configuração da biblioteca Typesafe Config, que move o Akka, o Play Framework, o Lagom e outros frameworks baseados em JVM. Os arquivos HOCON usam a extensão `.conf` e são um superconjunto estrito do JSON: todo arquivo JSON válido é HOCON válido.

O HOCON foi pensado para a configuração em tempo de execução de aplicações, e não para definir infraestrutura. Seu recurso de destaque são as substituições: a capacidade de referenciar outros valores de configuração no mesmo arquivo pela sintaxe de substituição, referenciando por caminho outros valores de configuração ou variáveis de ambiente. Isso torna o HOCON especialmente adequado à configuração em camadas: um arquivo base define padrões e um arquivo específico de ambiente sobrescreve valores individuais, com substituições puxando de variáveis de ambiente ou de outras fontes de configuração.

Fundamentos da sintaxe HOCON

# Configuração da aplicação
app {
  name = "my-service"
  version = "1.0.0"

  server {
    host = "0.0.0.0"
    port = 8080
    # Substituição a partir de uma variável de ambiente
    port = ${?APP_PORT}
  }

  database {
    url = "jdbc:postgresql://localhost:5432/mydb"
    # Substituição a partir de outro valor de configuração
    connection-pool = ${app.server.port}
  }
}

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

Recursos do HOCON além do JSON

• Comentários: comentários de uma linha com `#` e `//`; o JSON não aceita comentários.
• Substituições: `${path.to.value}` referencia outras chaves; `${?ENV_VAR}` não falha se a variável não estiver definida.
• Diretivas include: include "other.conf" funde arquivos de configuração externos no momento da análise.
• Fusão de objetos: chaves duplicadas fundem seus valores em vez de sobrescrevê-los; permite configuração em camadas.
• Flexibilidade de chave-valor: aceita key = value, key : value e key value (separado por espaço) de forma equivalente.
• Strings sem aspas: valores de string simples não precisam de aspas, a menos que contenham caracteres especiais.

HCL e HOCON resolvem problemas parecidos por ângulos diferentes. Os dois são mais legíveis que o JSON em configurações complexas, os dois aceitam comentários e os dois têm uma camada de compatibilidade com JSON. Mas seus objetivos de projeto, casos de uso principais e integrações de ecossistema são tão distintos que você raramente escolhe entre eles: a ferramenta que você usa escolhe por você.

HCL descreve qual infraestrutura deve existir. HOCON descreve como uma aplicação deve se comportar. A diferença de propósito molda cada decisão de projeto nas duas linguagens.

A diferença conceitual essencial

O HCL é imperativo quanto à estrutura: os blocos têm tipos e rótulos (`resource "aws_instance" "web"`) que carregam significado semântico interpretado pela ferramenta. Você declara entidades de um certo tipo com certas propriedades. O HOCON é puramente um formato de dados: define uma estrutura hierárquica de chave-valor que as aplicações leem ao iniciar. Não tem noção de blocos com tipo; tudo é uma chave apontando para um valor, um objeto ou uma lista.

Arquivos HCL são editados com mais frequência como parte de um projeto Terraform, embora os mesmos princípios valham para Packer, Vault e Nomad. Acertar no formato e na estrutura importa porque as ferramentas da HashiCorp validam o HCL de forma rígida na fase de plan ou validate, e blocos HCL malformados geram erros difíceis de rastrear se o arquivo não estiver consistentemente indentado.

Em projetos JVM, os arquivos de configuração HOCON normalmente ficam em `src/main/resources/application.conf`. Aplicações Akka usam HOCON para a configuração do sistema de atores, ajustes de dispatcher e configuração de extensões. O Play Framework usa para rotas, conexões de banco de dados e configurações da aplicação. O formato é permissivo (strings sem aspas, operadores de atribuição flexíveis, comentários), mas uma formatação sensível a espaços torna os arquivos mais fáceis de ler e manter.

Formatar arquivos HOCON

O Formatador HOCON do Aback Tools formata arquivos de configuração HOCON com indentação consistente de 4 espaços, espaçamento correto de chave-valor, tratamento limpo de substituições e as convenções do Typesafe Config. Isso é especialmente útil ao editar arquivos grandes de Akka ou Play que acumularam formatação inconsistente por causa de vários colaboradores.

Converter HOCON para YAML

Quando uma ferramenta do seu pipeline espera YAML mas a configuração da sua aplicação é HOCON, o Conversor de HOCON para YAML traduz a estrutura de chave-valor do HOCON para o equivalente em YAML. Note que os recursos específicos do HOCON (substituições, diretivas include e chaves fundidas) são resolvidos antes da conversão, então a saída YAML reflete a configuração final fundida, e não a sintaxe bruta do template HOCON.

HCL e HOCON convivem com um panorama mais amplo de formatos de configuração. Escolher o certo raramente é uma decisão livre: as ferramentas que você usa ditam o formato. Mas entender onde cada formato se encaixa ajuda a raciocinar sobre portabilidade de configuração e trade-offs de ferramentas.

Comparação dos principais formatos de configuração

HCL e YAML juntos em fluxos de trabalho com Terraform

Na prática, um projeto Terraform usa HCL para todas as definições de infraestrutura, enquanto o pipeline de CI/CD que roda o Terraform costuma ser configurado em YAML (GitHub Actions, GitLab CI, CircleCI). Os dois convivem sem conflito: o HCL é a entrada do Terraform e o YAML é a entrada do pipeline. Se você trabalha com os dois, a mesma disciplina de formatação se aplica. Para erros de YAML nos seus arquivos de CI, o fluxo de Como detectar e corrigir erros de YAML se aplica diretamente.

HOCON, TOML e YAML para configuração de aplicações

Para aplicações que não são JVM, TOML e YAML são escolhas mais comuns que HOCON. O TOML é o padrão do Rust (Cargo.toml), do empacotamento Python (pyproject.toml) e de sites estáticos em Hugo. O YAML domina Kubernetes, Ansible, Docker Compose e a maior parte das ferramentas cloud native. O HOCON é a escolha certa especificamente quando o seu runtime é um framework JVM que já vem com Typesafe Config: você ganha os recursos do HOCON de graça, e brigar com o framework para usar outro formato cria mais problemas do que resolve.

Artigos relacionados sobre formatos

Se você está avaliando formatos de configuração para um projeto novo, os artigos complementares desta série cobrem as alternativas mais próximas. Como criar um arquivo INI trata do formato de configuração mais simples. Como comentar em YAML corretamente detalha a sintaxe do YAML. E O que o terraform validate realmente verifica? mostra como erros de HCL aparecem em um fluxo de trabalho com Terraform.