Que sont HCL et HOCON ? Les langages de configuration expliqués

HCL signifie HashiCorp Configuration Language. C'est un langage de configuration dédié à un domaine, créé par HashiCorp en 2014, d'abord pour prendre en charge Terraform. Les fichiers HCL utilisent l'extension `.hcl` (ou `.tf` pour Terraform) et sont conçus pour être lisibles par l'humain, analysables par machine et compatibles JSON : tout document JSON valide est aussi du HCL valide.

HCL n'est pas un langage de programmation. Il ne peut pas effectuer de calculs, définir des fonctions ou contrôler le flux d'exécution comme Python ou JavaScript. C'est un langage de configuration déclaratif : vous décrivez l'état souhaité de l'infrastructure, et l'outil qui lit le HCL (Terraform, Packer, Vault, Consul, Nomad) détermine comment y parvenir. Cette contrainte est volontaire : elle rend les configurations HCL prévisibles et auditables.

Les bases de la syntaxe HCL

HCL utilise une structure en blocs avec des attributs, des blocs imbriqués et des expressions. Les attributs sont des paires clé-valeur ; les blocs regroupent des attributs liés et peuvent être imbriqués. Les commentaires utilisent `#` ou `//` sur une ligne et `/* */` sur plusieurs.

# Commentaire sur une ligne
resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

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

  # Bloc imbriqué
  root_block_device {
    volume_size = 20
    encrypted   = true
  }
}

Où HCL est utilisé

• Terraform : le principal consommateur de HCL ; chaque fichier `.tf` est du HCL qui décrit de l'infrastructure cloud ou sur site.
• Packer : HCL2 (la version 2 du langage) sert à définir la construction d'images machine pour les AMI AWS, les images GCP et autres.
• Vault : HCL est utilisé pour les fichiers de politique qui définissent les règles de contrôle d'accès dans HashiCorp Vault.
• Consul : les fichiers de configuration du maillage de services, les contrôles de santé et les définitions de service utilisent HCL.
• Nomad : les spécifications de tâches d'orchestration de charges sont écrites en HCL.

HOCON signifie Human-Optimized Config Object Notation. Il a été créé par Typesafe (aujourd'hui Lightbend) en 2011 comme format de configuration de la bibliothèque Typesafe Config, qui alimente Akka, Play Framework, Lagom et d'autres frameworks JVM. Les fichiers HOCON utilisent l'extension `.conf` et sont un surensemble strict de JSON : tout fichier JSON valide est du HOCON valide.

HOCON est conçu pour la configuration d'exécution des applications plutôt que pour la définition d'infrastructure. Sa fonctionnalité phare est la substitution : la possibilité de référencer d'autres valeurs de configuration dans le même fichier grâce à la syntaxe de substitution, en référençant par chemin d'autres valeurs de configuration ou des variables d'environnement. Cela rend HOCON particulièrement adapté à la configuration en couches : un fichier de base définit les valeurs par défaut, un fichier propre à un environnement remplace certaines valeurs, et les substitutions puisent dans les variables d'environnement ou d'autres sources.

Les bases de la syntaxe HOCON

# Configuration de l'application
app {
  name = "my-service"
  version = "1.0.0"

  server {
    host = "0.0.0.0"
    port = 8080
    # Substitution depuis une variable d'environnement
    port = ${?APP_PORT}
  }

  database {
    url = "jdbc:postgresql://localhost:5432/mydb"
    # Substitution depuis une autre valeur de configuration
    connection-pool = ${app.server.port}
  }
}

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

Les fonctionnalités HOCON au-delà de JSON

• Commentaires : commentaires sur une ligne avec `#` et `//` ; JSON n'en accepte aucun.
• Substitutions : `${path.to.value}` référence d'autres clés ; `${?ENV_VAR}` reste silencieux si la variable n'est pas définie.
• Directives include : include "other.conf" fusionne des fichiers externes au moment de l'analyse.
• Fusion d'objets : les clés dupliquées fusionnent leurs valeurs au lieu de les écraser ; permet la configuration en couches.
• Souplesse clé-valeur : accepte indifféremment key = value, key : value et key value (séparé par un espace).
• Chaînes sans guillemets : les valeurs de chaîne simples n'ont pas besoin de guillemets sauf si elles contiennent des caractères spéciaux.

HCL et HOCON résolvent des problèmes proches sous des angles différents. Les deux sont plus lisibles que JSON pour des configurations complexes, les deux acceptent les commentaires et les deux disposent d'une couche de compatibilité JSON. Mais leurs objectifs de conception, leurs cas d'usage principaux et leurs intégrations d'écosystème sont suffisamment distincts pour que vous choisissiez rarement entre eux : l'outil que vous utilisez choisit pour vous.

HCL décrit quelle infrastructure doit exister. HOCON décrit comment une application doit se comporter. Cette différence d'objectif façonne chaque décision de conception dans les deux langages.

La différence conceptuelle essentielle

HCL est impératif quant à la structure : les blocs ont des types et des étiquettes (`resource "aws_instance" "web"`) porteurs de sens, interprétés par l'outil. Vous déclarez des entités d'un certain type avec certaines propriétés. HOCON est purement un format de données : il définit une structure hiérarchique clé-valeur que les applications lisent au démarrage. Il n'a pas de notion de blocs typés ; tout est une clé pointant vers une valeur, un objet ou une liste.

Les fichiers HCL sont le plus souvent modifiés dans le cadre d'un projet Terraform, même si les mêmes principes s'appliquent à Packer, Vault et Nomad. Le formatage et la structure importent car les outils HashiCorp valident HCL de manière stricte au moment de plan ou validate, et des blocs HCL mal formés produisent des erreurs difficiles à tracer si le fichier n'est pas indenté de façon cohérente.

Dans les projets JVM, les fichiers de configuration HOCON se trouvent généralement dans `src/main/resources/application.conf`. Les applications Akka utilisent HOCON pour la configuration du système d'acteurs, les réglages de dispatcher et la configuration des extensions. Play Framework l'utilise pour les routes, les connexions aux bases de données et les réglages de l'application. Le format est permissif (chaînes sans guillemets, opérateurs d'affectation souples, commentaires), mais un formatage sensible aux espaces rend les fichiers plus faciles à lire et à maintenir.

Formater les fichiers HOCON

Le formateur HOCON d'Aback Tools formate les fichiers de configuration HOCON avec une indentation cohérente de 4 espaces, un espacement clé-valeur correct, une gestion propre des substitutions et les conventions Typesafe Config. C'est particulièrement utile lorsqu'on modifie de grands fichiers de configuration Akka ou Play dont le formatage est devenu incohérent au fil des contributions.

Convertir HOCON en YAML

Quand un outil de votre pipeline attend du YAML mais que la configuration de votre application est en HOCON, le convertisseur HOCON vers YAML traduit la structure clé-valeur HOCON en équivalent YAML. Notez que les fonctionnalités propres à HOCON (substitutions, directives include et clés fusionnées) sont résolues avant la conversion : la sortie YAML reflète donc la configuration finale fusionnée et non la syntaxe brute du modèle HOCON.

HCL et HOCON coexistent avec un paysage plus large de formats de configuration. Choisir le bon est rarement une décision libre : les outils que vous utilisez dictent le format. Mais comprendre où chaque format s'inscrit aide à raisonner sur la portabilité de la configuration et les compromis d'outillage.

Comparaison des principaux formats de configuration

HCL et YAML ensemble dans les workflows Terraform

En pratique, un projet Terraform utilise HCL pour toutes les définitions d'infrastructure, tandis que le pipeline CI/CD qui exécute Terraform est souvent configuré en YAML (GitHub Actions, GitLab CI, CircleCI). Les deux coexistent sans conflit : HCL est l'entrée de Terraform, YAML celle du pipeline. Si vous travaillez avec les deux, la même discipline de formatage s'applique. Pour les erreurs YAML dans vos fichiers de CI, la procédure de Comment détecter et corriger les erreurs YAML s'applique directement.

HOCON, TOML et YAML pour la configuration d'application

Pour les applications non JVM, TOML et YAML sont des choix plus courants que HOCON. TOML est le standard de Rust (Cargo.toml), du packaging Python (pyproject.toml) et des sites statiques Hugo. YAML domine Kubernetes, Ansible, Docker Compose et la plupart des outils cloud native. HOCON est le bon choix spécifiquement quand votre environnement d'exécution est un framework JVM livré avec Typesafe Config : vous obtenez les fonctionnalités de HOCON gratuitement, et se battre contre le framework pour utiliser un autre format crée plus de problèmes que cela n'en résout.

Articles liés sur les formats

Si vous évaluez des formats de configuration pour un nouveau projet, les articles complémentaires de cette série couvrent les alternatives les plus proches. Comment créer un fichier INI traite le format de configuration le plus simple. Comment commenter en YAML correctement détaille la syntaxe YAML. Et Que vérifie réellement terraform validate ? explique comment les erreurs HCL apparaissent dans un workflow Terraform.