Skip to content

Les Expressions et les Fonctions terraform

https://www.terraform.io/language/functions

1. Les types

1.1. types primitifs

  • string
  • number (entier ou décimaux)
  • bool

1.2. types complexes

  • list(< TYPE >) ou tuple([< TYPE >, < TYPE > ...])
    liste non ordonnée de différents items d'un même type, indexé par un entier de 0 à n.
    les tuples sont des listes avec des items de différents types.
    Symbole [] . Séparateur ','
    exemple : json mylist=["a", 15, true] mylist[0] -> a

  • set([< TYPE >]) liste ordonnée d'éléments d'un même type

  • map(< KEY > = < TYPE >)/map(< KEY > : < TYPE >) ou object({< ATTR NAME > = < TYPE >, ... })
    liste de clé-valeur. Les clés sont toujours des string.
    Symbole {}. Séparateur entre élément ','. Attribution '=' ou ':'
    Les maps sont des collections dont les valeurs sont d'un seul type
    Les objects sont des collections dont les valeurs peuvent avoir des types différents.
    exemple : ```json { name = "John" age = 52 }

``` - null
aucun type

1.3. Heredoc

Terraform support heredoc 

<<EOT
hello
world
EOT

ou avec incrémentation

<<-EOT
hello
  world
EOT

1.4 Substitution

${ ... } : Interpolation Replace par la valeur littérale du paramètre contenu entre les accolades exemple : 

`"Hello, ${var.name}!"`
si `var.name` = `"World"`
alors l'affichage sera `"Hello World"`

%{ ... } : Directive Elle permet des résultats conditionnels et/ou une itération sur les collections. * condition: %{if }/%{else}/%{endif} * itération: %{for in } / %{endfor}

Espace blanc: l'ajout d'un tilde ~ au niveau des accolades permet d'enlever les espaces avec les séquences. {~ if }/{ end ~} supprime les éventuels espaces avant et après la séquence. exemple 

<<EOT
%{ for ip in aws_instance.example.*.private_ip ~}
server ${ip}
%{ endfor ~}
EOT

donne

server 10.1.16.154
server 10.1.16.1
server 10.1.16.34

NB: $${ et %%{ permet d'échapper les séquences

2. Les expressions

2.1. Chemins des répertoires

il existe des mots clés pour les chemins (path)

  • path.module chemin du module où l'expression est placée
  • path.root chemin du module root. Répertoire parent.
  • path.cwd Chemin du répertoire de travail. Généralement c'est le même que pour path.root sauf dans des cas avancés de traitement.
  • terraform.workspace nom du workspace sélectionné

2.2. Expression spéciales d'itération

  • count.index: Accès à l'index de l'itérateur count en meta-argument.
  • each.key / each.value: Accès au clé/valeur d'une map utilisé dans le meta-argument for_each .
  • self: référence à la ressource uniquement dans les blocs provisioner et connection.

Récupération des données en itération count aws_instance.example[*].id retourne la liste de tous les ids de chaque instance example de la ressource aws_instance. aws_instance.example[0].id retourne uniquement l'id de la première instance example de la ressource aws_instance

Récupération des données en itération for_each aws_instance.example["a"].id retourne l'id de l'instance example qui a la clé "a" de la ressource aws_instance. [for value in aws_instance.example: value.id] retourne la liste de tous les ids de chaque instance example de la ressource aws_instance. values(aws_instance.example)[*].idéquivalent de l'expression précédent en version splat avec la fonction values()

2.3. Les opérateurs

Terraform utilisent les opérateurs classiques * d'arithmétiques (+,-,/,*,%), * de comparaison (<=, >=, <, >), * d'égalité (==, !=) * et de logiques ( &&, ||, !)

2.4. Expressions conditionnelles

condition ? true_val : false_val

2.5. Expression for

[for s in var.list : upper(s)] : retourne une liste/tuple de string en majuscule

[for k, v in var.map : length(k) + length(v)] : retourne une liste/tuple de nombre

{for s in var.list : s => upper(s)} : retourne un objet/map avec l'ancien valeur en clé et la transformation en valeur

list = ["foo", "bar", "baz"]
{for s in var.list : s => upper(s)}
{
  foo = "FOO"
  bar = "BAR"
  baz = "BAZ"
}

[for s in var.list : upper(s) if s != ""] retourne une liste/tuple de string en majuscule si la chaine de départ n'est pas vide

toset([for e in var.set : e.example]): permet de garder l'ordonnance de départ des éléments après l'expression for

2.6 L'opérateur splat [*]

C'est une opérateur si retourne une liste d'élément de l'instance comme l'opérateur for mais de manière plus concise.

var.list[*].id est équivalent à [for o in var.list : o.id]

ATTENTION: l'opérateur splat a un comportement spécial sur l'élément qui peut être nul et qui n'est ni une liste, ni un tuple, ni un set. Dans ce cas, l'opérateur retournera soit une valeur nulle soit une liste d'un seul élément.

exemple :

variable "website_setting" {
  type = object({
    index_document = string
    error_document = string
  })
  default = null
}
resource "aws_s3_bucket" "example" {
  # ...

  dynamic "website" {
    for_each = var.website_setting[*]
    content {
      index_document = website.value.index_document
      error_document = website.value.error_document
    }
  }
}

Dans ce cas, le bloc dynamique sera crée si et seulement si la variable website_setting est instanciée.

3. Les fonctions

3.1. fonctions numériques

Fonction Formule Role
abs abs(number) valeur absolue
ceil ceil(number) arrondi supérieur le plus proche
floor floor(number) arrondi inférieur le plus proche
log log(number, base) logarithme
max max(12, 54, 3)
max([12, 54, 3]...)		 max d'une suite de nombre
max d'une liste
min min(12, 54, 3)
min([12, 54, 3]...)		 min d'une suite de nombre
min d'une liste
parseint parseint(string, base) convertir une chaine en nombre suivant la base utilisée 10, 16, 2 (entre 2 et 62)
pow pox(num1, num2) élève num1 à la puissance num2
signum signum (number) détermine le signe du nombre. retourne -1, 0, 1

3.2 fonctions de chaine de caractères

Fonction Formule Role
chomp chomp("hello\n") supprime les marques de fin de paragraphe "\n" "\n\r" "\n\n"
format format(spec, values...) formate la chaine avec les caractères %s, %g, %t, %#v, etc...
formatlist formatlist(spec, values...) crée une liste de chaine en substitution %s...
indent indent(num_spaces, string) indente la chaine de num_spaces
join join(separator, list) retourne une chaine à partir d'un liste avec le séparateur spécifié
lower lower(string) retourne une chaine en minuscule
regex regex(pattern, string) applies a regular expression to a string and returns the matching substrings.
regexall regexall(pattern, string) applies a regular expression to a string and returns a list of all matches.
replace replace(string, subst, replace) searches a given string for another given substring, and replaces each occurrence with a given replacement string.
split split(separator, string) split produces a list by dividing a given string at all occurrences of a given separator.
strrev strrev(string) inverse les caractères d'une chaine
substr substr(string, offset, length) extrait le sous-chaine avec un décalage de offset sur length caractères
title title(string) met le premier caractère de chaque mot en majuscule
trim trim(string, str_character_set) supprime les caractères donnés de la chaine
trimprefix trimprefix(string, substring) supprime substring de chaque mot commençant par substring sinon retourne le mot complet
trimsuffix trimsuffix(string, substring) supprime substring de chaque mot se terminant par substring sinon retourne le mot complet
trimspace trimsspace(string) supprime les espaces en début et fin de chaine y compris retour, tabs et autres caractères d'espace
upper upper(string) Met la chaine en majuscule

3.3. fonctions de manipulation des collection

Fonction Formule Role
alltrue alltrue(list) retourne true si tous les éléments de la liste sont true ou "true"
anytrue anytrue(list) retourne true si au moins un élément de la liste est true ou "true"
chunklist chunklist(list, chunk_size) retourne une liste découpé en taille de chunk_size
coalesce coalesce(value, value, ...) retourne le premier élément des arguments qui n'est pas nul
coalescelist coalescelist(list, list, ...) retourne la première liste des arguments qui n'est pas vide
compact compact(list(string)) supprime les éléments vides
concat concat(list, list) concatène les listes (2 minimum) en une seule
contains contains(list, value) retourne true si la valeur recherchée est trouvée dans la liste
distinct distinct(list) retourne une liste d'élément unique - Supprime les doublons
element element(list, index) retourne l'élément à position d'index donnée (les index commence à 0)
flatten flatten([list, list, list]) retourne les éléments imbriquées en une liste d'un niveau pour les maps utiliser for_each
index index(list, value) donne l'index du premier élément recherché. Retourne une erreur si l'élément est absent
keys keys(map/object) retourne la liste des clés de la map ou de l'objet
length length(value) retourne la taille de la chaine, de la liste ou de la map. 0 si vide
lookup lookup(map, key, default) retourne la valeur de la clé sinon la valeur par défaut
matchkeys matchkeys(valueslist, keyslist, searchset) retourne une liste des valeurs qui ont le même index que les éléments de la deuxième liste qui corresponde à la valeur recherchée
merge merge(map, map, map...) fusionne des maps. En cas de clé identique, la dernière valeur est retenue
one one(list) retourne null ou le premier élément. Erreur si la liste comprend plus d'un élément
range range(max)
range(start, limit)
range(start, limit, step)		 créer une liste de nombre suivant les arguments donnés
reverse reverse(list) inverse l'ordre d'une liste
setintersection setintersection(sets...) Crée un set des éléments communs d'une collection de différents sets
setproduct setproduct(sets...) produit cartésien d'une collection de sets
setsubtract setsubtract(a, b) Produit un set d'élément présent dans le premier set non présent dans le deuxième
setunion setunion(sets...) Fusionne des sets en un seul set d'élément unique
slice slice(list, startindex, endindex) extrait les éléments consécutifs d'une liste de l'index startindex inclus à l'index endindex exclus
sort sort(list) trie une liste en ordre lexicographique
sum sum(list/set(number)) fait la somme des nombres contenus dans une liste ou un set
transpose transpose( { "a" = ["1","2"], "b" = ["2","3"] } )
{ "1" = ["a"], "2" = ["a","b"], "3"=["b"] }		 prend une map de liste de chaine et interverti les clés et les valeurs pour obtenir une nouvelle map de chaine.
values values(map) Retourne la liste des valeurs d'une map
zipmap zipmap(keyslist, valueslist) Construit une map à partir de deux listes de même taille. La keylist doit être une liste de string, mais la liste de valuelist peut être de n'importe quel type.

3.4. fonctions d'encodage

Fonction Formule Role
base64decode base64decode(string) prend une chaine codée en base64 et retourne la chaine originale
base64encode base64encode(string) prend une chaine et retourne une chaine codée en base64
base64gzip base64gzip(string) compresse une chaine en gzip et la code en base64
csvdecode csvdecode(string) décode une chaine au format CSV et créer une liste de maps représentant les données
jsondecode jsondecode(jsonstring) décode un chaine json en type terraform (string, number, bool, object, tuple)
jsonencode jsonencode(type) encode une type terraform en string json
urlencode urlencode(string) applique l'encode url à la chaine (%20,%21 etc...)
yamldecode yamldecode(yaml) transcode un string yaml en type terraform
yamlencode yamlencode(type) transcode un type terraform en élément yaml

3.5. fonctions de manipulation des fichiers et dossiers

Fonction Formule Role
abspath abspath(path.root) donne le chemin absolu du chemin donné en argument
dirname dirname(dir/file) donne l’arborescence des dossiers ou est contenu le fichier
pathexpand pathexpand(pathway) donne le chemin absolu si utilisation ~ ou Variable
basename basename(dir/file) donne le nom du fichier sans le chemin
file file(path) lit le contenu du fichier et le retourne sous forme de chaine
fileexists fileexists(path) retourne true si le fichier existe
fileset fileset(path, pattern) retourne la liste des fichiers avec leur chemin suivant le pattern donné (, *, ? {alternative,...}, [CLASS], [^CLASS], [abc], [a-z])
filebase64 filebase64(path) lit le contenu du fichier et le retourne en base64
templatefile templatefile(path, vars) lit le contenu du fichier et substitut les variables avec les valeurs données et renvoi une chaine. Le fichier utilise les expression d'interpolation (${...}) et de directive (%{...}). Il est recommandé que le fichier soit suffixé par .tftpl.

3.6. fonctions Date et Heure

Fonction Formule Role
formatdate formatdate(spec, timestamp) terraform utilise la convention RFC 3339
exemple formatdate("DD MMM YYYY hh:mm ZZZ", "2018-01-02T23:12:01Z")
timeadd timeadd(timestamp, duration) ajout une durée à un timestamp et retourne un autre timestamp
timestamp timestamp() retourne le temps en UTC suivant la convention RFC 3339
Terraform prend le temps à partir de la commande terraform apply (et non terraform plan)

3.7. fonctions de cryptographie et de hachage

Fonction Formule Role
base64sha256 base64sha256(string) donne le SHA256 de la chaine et l'encode en base64
base64sha512 base64sha512(string) donne le SHA512 de la chaine et l'encode en base64
bcrypt bcrypt(string, cost) hache la chaine en chiffrement Blowfish et retourne une chaine en format Modular Crypt. cost est optional, par défaut il vaut 10
filebase64sha256 filebase64sha256(file) hachage en SHA256 d'un fichier donné et l'encode en base64
filebase64sha512 filebase64sha512(file) hachage en SHA512 d'un fichier donné et l'encode en base64
filemd5 filemd5(file) hachage en MD5 d'un fichier donné
filesha1 filesha1(file) hachage en SHA1 d'un fichier donné
filesha256 filesha256(file) hachage en SHA256 d'un fichier donné
filesha512 filesha512(file) hachage en SHA512 d'un fichier donné
md5 md5(string) hachage en MD5 d'une chaine donnée
rsadecrypt rsadecrypt(ciphertext, privatekey) décrypte un texte encrypté RSA avec la clé et donne la valeur originale
sha1 sha1(string) hachage en SHA1 d'une chaine donnée
sha256 sha256(string) hachage en SHA256 d'une chaine donnée
sha512 sha512(string) hachage en SHA512 d'une chaine donnée
uuid uuid() Génère une identité pseudo-random unique au format RFC 4122 section 4.4
uuidv5 uuidv5(namespace, name) Génère une identité unique en RFC 4122 section 4.3, connu sous la "version 5" UUID.

3.8. fonctions réseaux IP

Fonction Formule Role
cidrhost cidrhost(prefix, hostnum) Calcul l'adresse IP complète avec le numéro du host et le préfixe CIDR.
Exemple cidrhost("10.12.112.0/20", 16) ==> 10.12.112.16
cidrnetmask cidrnetmask(prefix) Calcul le masque à partir du préfixe CIDR.
cidrsubnet cidrsubnet(prefix, newbits, netnum) Calcul le sous-réseau
Exemple cidrsubnet("172.16.0.0/12", 4, 2) ==> 172.18.0.0/16
cidrsubnet("10.1.2.0/24", 4, 15) ==> 10.1.2.240/28
cidrsubnets cidrsubnets(prefix, newbits...) calcule une séquence de plages d'adresses IP consécutives dans un préfixe CIDR particulier.

3.9. fonctions conversion de type

Fonction Formule Role
can can(expression) Evalue une expression et retourne true si par d'erreur
defaults defaults(input_value, defaults) attribue de manière concise des valeurs par défaut uniquement lorsqu'une valeur d'attribut a été définie sur null.
nonsensitive nonsensitive(sensitive_value) prend une valeur sensible et renvoie une copie de cette valeur avec le marquage sensible supprimé, exposant ainsi la valeur.
sensitive sensitive(value) prend n'importe quelle valeur et en renvoie une copie marquée sensible avec la même signification et le même comportement que pour les variables d'entrée sensibles
tobool tobool(value) convertie les chaines "true" et "false" et null, en booléen ou null. N'importe quelle autre valeur retourne une erreur. La conversion "true"->true et "false"->false est généralement implicite.
tolist tolist([val1, val2, val3,...]) convertie les arguments en liste (conversion implicite des valeurs en un même type)
tomap tomap({val1=value, val2=value,...}) convertie les arguments en map (conversion implicite des valeurs en un même type)
tonumber tonumber(value) conversion d'une valeur en nombre sinon erreur
toset toset([val1, val2, val3,...]) convertie les arguments en set (conversion implicite des valeurs en un même type et suppression des doublons)
tostring tostring(value) converti l'argument en chaine. Erreur si l'argument est une collection
try try{expr1, expr2,...} évalue tour à tour toutes ses expressions d'argument et renvoie le résultat de la première qui ne produit aucune erreur.
type type(value) retourne le type de l'argument

exemple try:

variable "example" {
  type = any
}

locals {
  example = try(
    [tostring(var.example)],
    tolist(var.example),
  )
}