Syntaxe HCL de base : commentaires, blocs et attributs

La syntaxe HCL repose sur peu d’éléments, mais il faut les reconnaître correctement dès le départ : des blocs, des arguments, des valeurs et parfois des templates de chaînes. Une fois cette base acquise, les fichiers Terraform et Packer deviennent immédiatement plus lisibles.

Cette page se concentre sur la forme du langage. Elle n’explique pas ce que fait un bloc resource ou provider dans Terraform. Elle vous apprend d’abord à lire la structure elle-même.

La structure minimale d’un fichier HCL

Le motif le plus courant est le bloc :

terraform {
  required_version = ">= 1.14.0"
}

Dans cet exemple :

terraform est le type de bloc ;
les accolades délimitent son contenu ;
required_version = ">= 1.14.0" est un argument avec une clé et une valeur.

Beaucoup de fichiers HCL suivent ce schéma général : un bloc principal, des arguments simples, puis parfois des blocs imbriqués.

Dans Packer, vous retrouverez la même logique de bloc avec d’autres types, par exemple :

source "docker" "alpine" {
  image  = "alpine:3.20"
  commit = true
}

La forme du langage ne change pas. Seul le schéma attendu par l’outil change.

Blocs, labels et arguments

Un bloc peut avoir zéro, un ou plusieurs labels selon le schéma attendu par l’outil.

resource "libvirt_volume" "ubuntu" {
  name = "ubuntu-24.04.qcow2"
  pool = "default"
}

Ici :

resource est le type de bloc ;
"libvirt_volume" et "ubuntu" sont deux labels ;
name et pool sont des arguments.

Les commentaires valides

HCL accepte trois formes de commentaires :

# commentaire sur une ligne
// autre commentaire sur une ligne

/*
commentaire
sur plusieurs lignes
*/

Si vous ne retenez que #, vous lirez quand même beaucoup de fichiers, mais vous finirez tôt ou tard par croiser // ou un bloc /* ... */.

Les chaînes et les templates

Les chaînes HCL s’écrivent avec des guillemets doubles :

name = "vm-dev"

Pour du texte multi-lignes, utilisez un heredoc :

cloud_init = <<-EOT
#cloud-config
hostname: vm-dev
EOT

Quand utiliser `${}`

L’interpolation ${...} sert à insérer une expression dans une chaîne :

locals {
  environment = "dev"
  vm_name     = "${local.environment}-web"
}

En revanche, une expression autonome n’a pas besoin de ${} :

count = var.instance_count

Ce point évite une erreur classique : croire que ${} est le délimiteur normal de toute expression HCL. Ce n’est pas le cas.

Les valeurs littérales les plus courantes

Quelques formes reviennent partout :

enabled = true
memory  = 2048
name    = "vm-dev"

tags = {
  env  = "dev"
  team = "platform"
}

subnets = ["frontend", "backend"]

Vous manipulez ici :

un booléen ;
un nombre ;
une chaîne ;
un objet ou une map littérale avec {} ;
une collection avec [].

Le détail des types est traité dans le guide suivant : Types et collections HCL.

Blocs imbriqués

Quand un outil attend une structure répétable ou plus riche, vous pouvez avoir un bloc dans un bloc :

resource "libvirt_domain" "vm" {
  name = "vm-dev"

  network_interface {
    network_name = "default"
  }
}

network_interface n’est pas une valeur de type map. C’est un bloc imbriqué que Terraform interprète selon le schéma du provider.

Erreurs fréquentes

Utiliser des guillemets simples comme 'dev' au lieu de "dev".
Traiter un bloc comme une map alors qu’il dépend du schéma de l’outil.
Mettre ${} autour d’une expression autonome qui n’en a pas besoin.
Croire que HCL décide lui-même quels blocs sont autorisés, alors que cela dépend de Terraform, Packer ou d’un autre outil.

À retenir

HCL s’appuie surtout sur des blocs, des arguments et des valeurs littérales.
Les commentaires valides sont #, // et /* ... */.
Les chaînes utilisent des guillemets doubles ou un heredoc.
${} sert pour les templates dans une chaîne, pas comme emballage systématique de toute expression.

Prochaines étapes

Types et collections HCL Le bon complément si vous hésitez entre list, map, object, tuple et contraintes de type

Expressions HCL Le prolongement naturel si vous voulez mieux lire interpolations, conditions et transformations

Templates HCL2 Packer À lire si vous manipulez surtout des fichiers .pkr.hcl et des blocs source ou build

Expressions Terraform À lire si votre difficulté porte surtout sur les références et les calculs côté Terraform