Écrire du code Terraform

Le langage déclaratif HCL

HCL, pour HashiCorp Configuration Language, est le langage dédié pour décrire les ressources manipulées par Terraform.

Ce langage se veut déclaratif. Plutôt que d’utiliser des commandes de manière séquentielle, comme « Créer une base de données » ou « Attacher une adresse IP », Terraform propose aux utilisateurs de décrire l’état de l’infrastructure souhaité.

Sa structure est proche de JSON ou YAML. Il est d’ailleurs possible d’écrire du code Terraform en JSON. Cependant, HCL est moins verbeux, et plus simple d’écriture que JSON.

Pour permettre aux utilisateurs de décrire leur infrastructure, Terraform propose deux types de blocs principaux. Les blocs resource permettent de décrire un objet de cloud ou d’API qui devra être créé et maintenu par Terraform. Une ressource sera par exemple une machine virtuelle ou une base de données sur un cloud public, un groupe Active Directory ou LDAP, un enregistrement DNS, etc.

Voici un exemple d’un bloc resource déclarant une base de données PostgreSQL sur le cloud public Scaleway :

resource "scaleway_rdb_instance" "main" { 
  name = "sw-db" 
  node_type = "DB-DEV-S" ...

Les fichiers .tf

Le code Terraform doit être écrit dans des fichiers dont l’extension est .tf. Voici un exemple d’arborescence de fichiers contenant du code Terraform :

. 
├── .gitignore 
├── main.tf 
├── outputs.tf 
├── provider.tf 
├── README.md 
└── variables.tf 

Ce code contient plusieurs fichiers en plus des fichiers .tf. Le fichier README.md est un fichier de documentation à destination des utilisateurs du code et des développeurs. Le fichier .gitignore est un fichier de configuration interprété par Git. Un exemple d’un tel fichier est décrit dans le chapitre Outils externes - .gitignore.

Les autres fichiers ont l’extension .tf et contiennent donc du code Terraform. Par convention, le fichier main.tf est considéré comme le point d’entrée du code. Le fichier provider.tf contient la configuration des providers (cf. section Le bloc provider de ce chapitre). Les fichiers variables.tf et outputs.tf sont consacrés aux blocs portant le même nom.

Voici un autre exemple d’arborescence de fichiers de code Terraform :

. 
├── .gitignore 
├── databases.tf 
├── instances.tf 
├── main.tf 
├── networks.tf 
├──...

Les blocs resource et data

resource "<TYPE>" "<NOM>" { 
  <ARGUMENT> = <EXPRESSION> 
} 

Les blocs variable, locals et output

Terraform permet aussi de définir des entrées et sorties dans le code, pour rendre le code réutilisable. Les entrées sont définies par des blocs variable, et les sorties par des blocs output.

Pour rendre le code plus lisible, il est également possible de définir des variables locales, qui pourront être réutilisées dans l’ensemble du code et qui sont définies par un bloc locals.

variable "instance_type" { 
  description = "type de machine" 
  type = string 
  default = "DB-DEV-S" 
} 
 
resource "scaleway_rdb_instance" "main" { 
  node_type = var.instance_type 
  engine = "PostgreSQL-11" 
} 

Les expressions

Les expressions sont les éléments du langage que l’on peut utiliser dans le code Terraform. Elles permettent de faire référence à d’autres éléments de code, d’effectuer des calculs, d’appeler des fonctions, etc.

variable "region" {} 
 
variable "bucket_name" {} 
 
variable "project_name" {} 
 
locals { 
  // a local can reference a variable 
  region = var.region 
  // a local can reference a data 
  project_id = data.scaleway_account_project.project.project_id 
} 
 
data "scaleway_account_project" "project" { 
  name = var.project_name 
} ...

Le bloc provider

Les providers sont les plug-ins Terraform, qui contiennent le code nécessaire pour interagir avec les API des services cloud. Les providers définissent des ressources et data qui peuvent alors être utilisées dans le code Terraform.

Les providers doivent être configurés de deux façons. La première consiste à déclarer dans le code Terraform les dépendances requises. Ces dépendances listent les providers utilisés dans le code, leur source et le numéro de version souhaité. Ces dépendances sont utilisées par la commande terraform init pour télécharger les providers.

La seconde configuration consiste à donner à chaque provider les éléments requis pour se connecter aux API du service cloud. Ces éléments sont souvent des clés d’accès, clés d’API, identifiants de projets, organisations ou namespaces en fonction des services.

terraform { 
  required_providers { 
    NAME = { 
      source = "SOURCE" 
      version...

Conventions de nommage

Terraform n’impose pas de convention de nommage particulière. Les noms de blocs resource, data, variable ou output doivent être des chaînes de caractères contenant des lettres, chiffres, underscores _ et tirets -.

Par convention, il est préférable de toujours privilégier l’utilisation de la convention dite Snake Case, avec uniquement des minuscules, et des underscores à la place des tirets.

Par exemple, privilégier le nom app_database au nom app-database.

Cette convention est suivie par le langage, avec par exemple la directive for_each, qui sera vue dans le chapitre Concepts avancés de Terraform - for_each, et également par le nommage de l’ensemble des ressources, comme dans notre exemple, avec le nom de la ressource scaleway_rdb_instance.

Il est aussi recommandé de simplifier les noms des ressources, en n’incluant pas le type de la ressource dans son nom. Par exemple, pour une ressource de type aws_s3_bucket qui servirait à archiver des fichiers, le nom suivant est recommandé :

resource "aws_s3_bucket" "archive" {} 

Il faut éviter de nommer...