Что такое HCL и HOCON? Языки конфигурации с объяснением

HCL расшифровывается как HashiCorp Configuration Language. Это предметно-ориентированный язык конфигурации, созданный HashiCorp в 2014 году, изначально для поддержки Terraform. Файлы HCL используют расширение `.hcl` (или `.tf` именно для Terraform) и рассчитаны на читаемость человеком, разбор машиной и совместимость с JSON: любой корректный документ JSON является корректным HCL.

HCL не является языком программирования. Он не выполняет вычислений, не определяет функции и не управляет ходом программы так, как Python или JavaScript. Это декларативный язык конфигурации: вы описываете желаемое состояние инфраструктуры, а инструмент, читающий HCL (Terraform, Packer, Vault, Consul, Nomad), решает, как его достичь. Это ограничение намеренно — оно делает конфигурации HCL предсказуемыми и проверяемыми.

Основы синтаксиса HCL

HCL использует блочную структуру с атрибутами, вложенными блоками и выражениями. Атрибуты — это пары «ключ — значение»; блоки группируют связанные атрибуты и могут быть вложенными. Комментарии задаются `#` или `//` для одной строки и `/* */` для нескольких.

# Однострочный комментарий
resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

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

  # Вложенный блок
  root_block_device {
    volume_size = 20
    encrypted   = true
  }
}

Где используется HCL

• Terraform — основной потребитель HCL; каждый файл `.tf` это HCL, описывающий облачную и локальную инфраструктуру.
• Packer — на HCL2 (вторая версия языка) описываются сборки образов машин для AMI AWS, образов GCP и других.
• Vault — HCL используется в файлах политик, определяющих правила контроля доступа в HashiCorp Vault.
• Consul — файлы конфигурации сервисной сети, проверки работоспособности и описания сервисов пишутся на HCL.
• Nomad — спецификации заданий оркестрации нагрузок пишутся на HCL.

HOCON расшифровывается как Human-Optimized Config Object Notation. Он создан Typesafe (сегодня Lightbend) в 2011 году как формат конфигурации библиотеки Typesafe Config, которая лежит в основе Akka, Play Framework, Lagom и других JVM-фреймворков. Файлы HOCON используют расширение `.conf` и являются строгим надмножеством JSON: любой корректный файл JSON корректен и как HOCON.

HOCON предназначен для конфигурации приложений во время выполнения, а не для описания инфраструктуры. Его главная особенность — подстановки: возможность ссылаться на другие значения конфигурации в том же файле с помощью синтаксиса подстановки, обращаясь по пути к другим значениям или переменным окружения. Это делает HOCON особенно удобным для многоуровневой конфигурации: базовый файл задаёт значения по умолчанию, файл для конкретной среды переопределяет отдельные значения, а подстановки берут данные из переменных окружения или других источников.

Основы синтаксиса HOCON

# Конфигурация приложения
app {
  name = "my-service"
  version = "1.0.0"

  server {
    host = "0.0.0.0"
    port = 8080
    # Подстановка из переменной окружения
    port = ${?APP_PORT}
  }

  database {
    url = "jdbc:postgresql://localhost:5432/mydb"
    # Подстановка из другого значения конфигурации
    connection-pool = ${app.server.port}
  }
}

# Списки
allowed-origins = ["https://example.com", "https://api.example.com"]

Возможности HOCON помимо JSON

• Комментарии — однострочные комментарии `#` и `//`; JSON комментариев не поддерживает.
• Подстановки — `${path.to.value}` ссылается на другие ключи; `${?ENV_VAR}` не вызывает ошибки, если переменная не определена.
• Директивы include — include "other.conf" объединяет внешние файлы конфигурации на этапе разбора.
• Слияние объектов — повторяющиеся ключи сливают значения вместо перезаписи; это позволяет строить слоистую конфигурацию.
• Гибкость записи «ключ — значение» — равнозначно поддерживаются key = value, key : value и key value (через пробел).
• Строки без кавычек — простые строковые значения не требуют кавычек, если не содержат специальных символов.

HCL и HOCON решают похожие задачи с разных сторон. Оба читабельнее JSON для сложных конфигураций, оба поддерживают комментарии и оба имеют слой совместимости с JSON. Но их цели проектирования, основные сценарии и интеграции с экосистемами настолько различны, что выбирать между ними почти не приходится — инструмент выбирает за вас.

HCL описывает, какая инфраструктура должна существовать. HOCON описывает, как должно вести себя приложение. Разница в назначении определяет каждое проектное решение в обоих языках.

Ключевое концептуальное различие

HCL императивен по структуре: блоки имеют типы и метки (`resource "aws_instance" "web"`), несущие смысл, который интерпретирует инструмент. Вы объявляете сущности определённого типа с определёнными свойствами. HOCON — чисто формат данных: он задаёт иерархическую структуру «ключ — значение», которую приложения читают при запуске. Понятия типизированных блоков здесь нет; всё это ключ, указывающий на значение, объект или список.

Файлы HCL чаще всего правят в рамках проекта Terraform, хотя те же принципы применимы к Packer, Vault и Nomad. Корректность форматирования и структуры важна, потому что инструменты HashiCorp строго проверяют HCL на этапе plan или validate, а неправильно оформленные блоки дают ошибки, которые трудно отследить, если файл не имеет единообразных отступов.

В проектах JVM файлы конфигурации HOCON обычно лежат в `src/main/resources/application.conf`. Приложения Akka используют HOCON для настройки акторной системы, параметров диспетчеров и конфигурации расширений. Play Framework применяет его для маршрутов, подключений к базе данных и настроек приложения. Формат снисходителен к записи (строки без кавычек, гибкие операторы присваивания, комментарии), но форматирование с учётом отступов делает файлы понятнее и проще в поддержке.

Форматирование файлов HOCON

Форматтер HOCON от Aback Tools форматирует конфигурации HOCON с единообразным отступом в 4 пробела, правильными интервалами «ключ — значение», аккуратной обработкой подстановок и соглашениями Typesafe Config. Это особенно полезно при правке больших конфигураций Akka или Play, где форматирование стало неоднородным из-за разных авторов.

Конвертация HOCON в YAML

Когда инструменту в вашем конвейере нужен YAML, а конфигурация приложения написана на HOCON, конвертер HOCON в YAML переводит структуру «ключ — значение» в эквивалент YAML. Учтите, что особенности HOCON (подстановки, директивы include и слитые ключи) разрешаются до конвертации, поэтому итоговый YAML отражает финальную объединённую конфигурацию, а не исходный синтаксис шаблона HOCON.

HCL и HOCON существуют в более широком ландшафте форматов конфигурации. Выбор подходящего редко бывает свободным: инструменты, которые вы используете, диктуют формат. Но понимание того, где какой формат уместен, помогает рассуждать о переносимости конфигурации и компромиссах в инструментах.

Сравнение основных форматов конфигурации

HCL и YAML вместе в работе с Terraform

На практике проект Terraform использует HCL для всех описаний инфраструктуры, а конвейер CI/CD, который запускает Terraform, часто настроен на YAML (GitHub Actions, GitLab CI, CircleCI). Они сосуществуют без конфликта: HCL — вход Terraform, YAML — вход конвейера. Если вы работаете с обоими, дисциплина форматирования нужна одинаковая. Для ошибок YAML в файлах CI напрямую применим разбор из статьи Как находить и исправлять ошибки YAML.

HOCON, TOML и YAML для конфигурации приложений

Для приложений, не работающих на JVM, TOML и YAML встречаются чаще, чем HOCON. TOML — стандарт для Rust (Cargo.toml), упаковки Python (pyproject.toml) и статических сайтов на Hugo. YAML доминирует в Kubernetes, Ansible, Docker Compose и большинстве cloud-native инструментов. HOCON — правильный выбор именно тогда, когда ваш рантайм это JVM-фреймворк со встроенным Typesafe Config: возможности HOCON достаются бесплатно, а борьба с фреймворком ради другого формата создаёт больше проблем, чем решает.

Связанные материалы о форматах

Если вы оцениваете форматы конфигурации для нового проекта, парные статьи этой серии рассматривают ближайшие альтернативы. Как создать файл INI описывает самый простой формат конфигурации. Как правильно комментировать в YAML разбирает особенности синтаксиса YAML. А Что на самом деле проверяет terraform validate? показывает, как ошибки HCL проявляются именно в рабочем процессе Terraform.