Variable - Terraform - Centre de documentation Alibaba Cloud

Présentation

Les exemples précédents utilisaient des valeurs codées en dur pour les arguments de ressource. Les variables d'entrée permettent de paramétrer la configuration, de standardiser le code et de personnaliser les propriétés des ressources lors de l'étape d'application.

Les variables d'entrée offrent les avantages suivants :

Améliorer la réutilisabilité

Les variables d'entrée dissocient l'affectation des attributs du code source. Vous pouvez ainsi personnaliser et partager la même configuration sans la modifier.
Améliorer la flexibilité

Une fois une variable définie, spécifiez sa valeur à l'exécution de plusieurs manières : via des variables d'environnement, des options CLI ou des fichiers clé-valeur. Dans l'exemple suivant, le nom, la description et le bloc CIDR sont codés en dur. Déclarez n'importe lequel de ces arguments comme variable et spécifiez leurs valeurs à l'exécution.

resource "alicloud_vpc" "my_vpc" {
  vpc_name    = "main-vpc"
  cidr_block  = "10.0.0.0/16"
  description = "my first vpc network"
}

Syntaxe des variables

Déclarez une variable d'entrée à l'aide d'un bloc variable.

Déclarez les variables d'entrée dans un bloc variable. Nous vous recommandons de regrouper toutes les déclarations de variables d'un module dans un seul fichier nommé variables.tf.

Le libellé qui suit le mot-clé variable correspond au nom de la variable. Les noms de variables doivent respecter deux règles :

Être uniques au sein d'un module.

Un nom de variable doit être unique parmi toutes les variables du même module. Une variable d'un module enfant peut porter le même nom qu'une variable du module parent, car elles existent dans des portées distinctes.
Ne pas être un mot-clé réservé.

Un nom de variable ne peut pas correspondre à un mot-clé réservé de Terraform, tel que les méta-arguments count et for_each.

Un bloc variable peut être vide, car aucun de ses arguments n'est obligatoire. Si vous omettez une valeur par défaut, Terraform déduit le type de la variable à partir de la valeur fournie à l'exécution.

type

L'argument type spécifie les types de valeurs acceptés par la variable. Terraform prend en charge les types primitifs suivants :

bool : une valeur booléenne, soit true soit false (sans guillemets).
number : une valeur numérique.
string : une séquence de caractères textuels.

default

L'argument default assigne une valeur par défaut à la variable, ce qui rend cette dernière facultative.

Pour accéder à la valeur d'une variable déclarée au sein d'un module, utilisez l'expression var.. Dans l'exemple suivant, la variable vpc_cidr_block est référencée en tant que var.vpc_cidr_block dans le bloc de ressource et assignée à l'argument cidr_block. La ressource utilise la valeur par défaut de la variable, entourée de guillemets.

resource "alicloud_vpc" "my_vpc" {
  vpc_name    = "main-vpc"
  cidr_block  = var.vpc_cidr_block
  description = ""
}
variable "vpc_cidr_block" {
  default = "10.0.0.0/16"
}

Le nom de la variable dans le bloc variable doit correspondre à la référence dans le bloc de ressource. Remplacez la valeur par défaut via une variable d'environnement, un fichier .tfvars ou l'option CLI -var. Par exemple :

# Override the default value using the -var CLI option
$ terraform plan -var 'vpc_cidr_block=172.16.0.0/16'

description

L'argument description documente l'objectif de la variable. Si une variable n'a pas de valeur default, Terraform affiche la description lorsqu'il demande une valeur lors d'une opération plan ou apply :

$ terraform plan
var.vpc_cidr_block
  A CIDR block for the VPC.
  Enter a value:

La chaîne description est souvent incluse dans la documentation et doit expliquer l'objectif de la variable ainsi que la valeur attendue. Rédigez-la du point de vue de l'utilisateur, et non de celui du mainteneur. Utilisez les commentaires de code pour les notes destinées aux mainteneurs.

sensitive

Définir l'argument sensitive sur true empêche Terraform d'afficher la valeur de la variable dans la sortie de commande ou les fichiers journaux. La valeur est masquée dans la sortie de terraform plan et terraform apply.

Utilisez cet argument pour les informations sensibles telles que les identifiants de base de données, les paires AccessKey ou les mots de passe de connexion. Marquer une variable comme sensible réduit le risque d'exposition accidentelle de données confidentielles.

Dans cet exemple, la variable vpc_cidr_block est marquée comme sensible. La ressource my-vpc utilise cette variable. Lorsque vous exécutez terraform plan ou apply, la valeur n'est pas affichée :

$ terraform plan
Terraform will perform the following actions:
  # alicloud_vpc.my-vpc will be created
  + resource "alicloud_vpc" "my-vpc" {
      + cidr_block            = (sensitive value)
      + create_time           = (known after apply)
      + id                    = (known after apply)
      + status                = (known after apply)
      + user_cidrs            = (known after apply)
      + vpc_name              = "main-vpc"
      ...
    }
Plan: 1 to add, 0 to change, 0 to destroy.

validation

Validez les valeurs assignées à une variable en incluant un ou plusieurs sous-blocs validation au sein du bloc variable. Chaque bloc validation comprend un argument condition qui spécifie la règle de validation.

Dans l'exemple suivant, les fonctions length et substr servent de condition pour vérifier que la valeur de vpc_name contient plus de 4 caractères et commence par tf- :

variable "vpc_name" {
  validation {
    condition     = length(var.vpc_name) > 4 && substr(var.vpc_name, 0, 3) == "tf-"
    error_message = "The VPC name must start with 'tf-' and be longer than 4 characters."
  }
}

Lorsque vous exécutez terraform plan et saisissez my-vpc comme valeur pour vpc_name, la règle de validation se déclenche et renvoie le message d'erreur spécifié :

Error: Invalid value for variable
  on main.tf line 66:
  66: variable "vpc_name" {
    var.vpc_name is "my-vpc"
The VPC name must start with 'tf-' and be longer than 4 characters.
This was checked by the validation rule at main.tf:67,3-13.

Définition des variables

Définissez les valeurs des variables à l'exécution de plusieurs manières :

# .tfvars file (recommended)
$ terraform apply -var-file my-vars.tfvars
# CLI option
$ terraform apply -var vpc_cidr_block="172.16.0.0/16"
# Environment variable
$ export TF_VAR_vpc_cidr_block="172.16.0.0/16"
$ terraform apply
# Default variable file terraform.tfvars
$ terraform apply

Utilisez les fichiers .tfvars pour basculer rapidement entre différents ensembles de variables et les gérer via le contrôle de version. Les options CLI conviennent pour valider rapidement des configurations simples. Les variables d'environnement fonctionnent bien dans les scripts et les pipelines. Si aucune méthode ne définit une variable requise, la CLI vous invite à saisir une valeur.

Lorsque vous devez définir de nombreuses variables, en particulier celles ayant des types complexes, les options CLI deviennent difficiles à manipuler. Spécifiez plutôt les valeurs des variables sous forme de paires clé-valeur dans un fichier avec l'extension .tfvars ou .tfvars.json, et transmettez le fichier avec l'option -var-file lorsque vous exécutez terraform plan ou terraform apply :

$ terraform plan -var-file my-vars.tfvars

Les définitions de variables dans les fichiers avec l'extension .tfvars ou .tfvars.json suivent la même syntaxe que HCL, mais ne contiennent que des affectations aux noms de variables. Terraform charge automatiquement les fichiers de variables nommés terraform.tfvars, terraform.tfvars.json, .auto.tfvars ou .auto.tfvars.json lorsque vous exécutez la commande plan ou apply, ce qui élimine la nécessité d'utiliser l'option -var-file. Les définitions dans un fichier .tfvars remplacent les valeurs par défaut des variables et les définitions issues des variables d'environnement. Pour remplacer la valeur d'une variable issue d'un fichier .tfvars depuis la ligne de commande, utilisez l'option -var au format -var="<variable_name>=<variable_value>". Par exemple, pour spécifier vpc_name comme "my-first-vpc" lorsque vous exécutez terraform plan, procédez comme suit :

$ terraform plan -var 'vpc_name=my-first-vpc'

La sortie de terraform plan affiche alors la valeur de vpc_name comme my-first-vpc, et non my-vpc tel que défini dans le fichier .tfvars. Cela s'avère utile dans les pipelines automatisés où vous transmettez dynamiquement des valeurs à l'indicateur -var pour remplacer les valeurs prédéfinies.

L'option CLI -var possède la priorité la plus élevée et remplace les valeurs définies par toute autre méthode.

Si une variable requise (une variable sans valeur default) ne reçoit aucune valeur par aucune méthode, Terraform vous invite à saisir une valeur lorsque vous exécutez plan ou apply. Par exemple, si vpc_name n'a aucune valeur assignée, la CLI invite à la saisie :

$ terraform plan
var.vpc_name
  Enter a value:

Bonnes pratiques

Suivez ces bonnes pratiques lors de la déclaration des variables :

Paramétrez uniquement ce qui doit changer

Exposez une variable uniquement lorsqu'elle doit changer entre les instances ou les environnements. Évitez le sur-paramétrage. L'ajout ou la modification d'une variable avec une valeur default est rétrocompatible, mais la suppression d'une variable constitue une rupture de compatibilité.
Privilégiez les fichiers .tfvars pour les modules racines

Pour les modules racines, utilisez des fichiers .tfvars pour définir les valeurs des variables. Évitez d'alterner entre les fichiers de variables et les options de ligne de commande. Les options CLI sont temporaires, facilement oubliées et ne peuvent pas être validées dans le contrôle de version. Un fichier de variable par défaut est plus prévisible.
Nommez les variables selon leur objectif

Pour les variables numériques telles que la taille du disque, la taille de la mémoire ou la période de paiement, incluez l'unité dans le nom de la variable. L'API Open d'Alibaba Cloud ne dispose pas d'unités standard, donc cette convention clarifie l'unité d'entrée attendue pour les mainteneurs. Pour les variables logiques, utilisez un nom formulé positivement, tel que enable_ipv6, afin de simplifier la logique conditionnelle.
Fournissez une description pour chaque variable

Les descriptions sont automatiquement incluses dans la documentation et fournissent un contexte aux nouveaux développeurs, ce qui améliore la lisibilité et la maintenabilité de votre configuration Terraform.