Bonnes pratiques pour les modules racine

Ce document fournit des consignes et des recommandations à prendre en compte lors de l'utilisation de modules racine.

Les configurations racines (modules racines) sont les répertoires de travail à partir desquels vous exécutez la CLI Terraform. Assurez-vous que les configurations racines respectent les normes suivantes standards (et les consignes Terraform précédentes, le cas échéant). Les recommandations explicites pour les modules racine remplacent les consignes générales.

Ce guide n'est pas une introduction à Terraform. Pour une présentation de l'utilisation de Terraform avec Google Cloud, consultez la page Premiers pas avec Terraform.

Réduire le nombre de ressources de chaque module racine

Il est important d'éviter que la configuration racine unique ne devienne trop volumineuse, avec un trop grand nombre de ressources stockées dans le même répertoire et dans le même état. Toutes les ressources d'une configuration racine spécifique sont actualisées à chaque exécution de Terraform. Cela peut ralentir l'exécution si de trop nombreuses ressources sont incluses dans un seul état. En règle générale : n'incluez pas plus de 100 ressources (idéalement, quelques douzaines tout au plus) dans un seul état.

Utiliser des répertoires distincts pour chaque application

Pour gérer des applications et des projets indépendamment les uns des autres, placez les ressources de chaque application et de chaque projet dans leurs propres répertoires Terraform. Un service peut représenter une application particulière ou un service commun tel qu'un réseau partagé. Imbriquez tout le code Terraform d'un service donné dans un seul répertoire (avec des sous-répertoires).

Diviser les applications en sous-répertoires spécifiques à l'environnement

Lors du déploiement de services dans Google Cloud, divisez la configuration Terraform du service en deux répertoires de premier niveau : un répertoire modules qui contient la configuration réelle du service, et un répertoire environments contenant la configuration racine de chaque environnement.

-- SERVICE-DIRECTORY/
   -- OWNERS
   -- modules/
      -- <service-name>/
         -- main.tf
         -- variables.tf
         -- outputs.tf
         -- provider.tf
         -- README
      -- ...other…
   -- environments/
      -- dev/
         -- backend.tf
         -- main.tf

      -- qa/
         -- backend.tf
         -- main.tf

      -- prod/
         -- backend.tf
         -- main.tf

Utiliser des répertoires d'environnement

Pour partager du code entre plusieurs environnements, référencez les modules. En général, il peut s'agir d'un module de service qui inclut la configuration Terraform partagée de base pour le service. Dans les modules de service, codez en dur les entrées courantes et ne demandez des entrées spécifiques à l'environnement que sous forme de variables.

Chaque répertoire d'environnement doit contenir les fichiers suivants :

  • Un fichier backend.tf qui déclare l'emplacement de l'état du backend Terraform (généralement Cloud Storage)
  • Un fichier main.tf qui instancie le module de service

Chaque répertoire d'environnement (dev, qa, prod) correspond à un espace de travail Terraform par défaut et déploie une version du service dans cet environnement. Ces espaces de travail isolent les ressources spécifiques à l'environnement dans leurs propres contextes. Utilisez uniquement l'espace de travail par défaut.

Il n'est pas recommandé d'avoir plusieurs espaces de travail CLI dans un environnement pour les raisons suivantes :

  • Il peut être difficile d'inspecter la configuration dans chaque espace de travail.
  • Il n'est pas recommandé d'avoir un seul backend partagé pour plusieurs espaces de travail, car ce backend partagé devient un point de défaillance unique s'il est utilisé pour la séparation des environnements.
  • Bien que la réutilisation du code soit possible, il devient plus difficile de lire le code lorsqu'il est nécessaire de changer de code en fonction de la variable d'espace de travail actuelle (par exemple, terraform.workspace == "foo" ? this : that).

Pour en savoir plus, consultez les ressources suivantes :

Exposer les sorties via un état distant

Veillez à exposer les résultats utiles des instances de module à partir d'un module racine.

Par exemple, l'extrait de code suivant transmet la sortie de l'ID de projet de l'instance du module de fabrique de projets en tant que sortie du module racine.

# Project root module
terraform {
  backend "gcs" {
    bucket  = "BUCKET"
  }
}

module "project" {
  source  = "terraform-google-modules/project-factory/google"
  ...
}

output "project_id" {
  value       = module.project.project_id
  description = "The ID of the created project"
}

Les autres environnements et applications Terraform ne peuvent référencer que des sorties au niveau du module racine.

En utilisant un état distant, vous pouvez référencer les sorties du module racine. Pour autoriser l'utilisation par d'autres applications dépendantes à des fins de configuration, veillez à exporter les informations liées aux points de terminaison d'un service vers un état distant.

# Networks root module
data "terraform_remote_state" "network_project" {
  backend = "gcs"

  config = {
    bucket = "BUCKET"
  }
}

module "vpc" {
  source  = "terraform-google-modules/network/google"
  version = "~> 9.0"

  project_id   = data.terraform_remote_state.network_project.outputs.project_id
  network_name = "vpc-1"
  ...
}

Parfois, par exemple lorsque vous appelez un module de service partagé à partir de répertoires d'environnement, il convient de réexporter l'intégralité du module enfant, comme suit :

output "service" {
  value       = module.service
  description = "The service module outputs"
}

Épingler aux versions de fournisseurs mineures

Dans les modules racine, déclarez chaque fournisseur et épinglez-le à une version mineure. Cela permet la mise à niveau automatique avec les nouveaux correctifs publiés, tout en conservant une cible fiable. Par souci de cohérence, nommez le fichier de versions versions.tf.

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 4.0.0"
    }
  }
}

Stocker les variables dans un fichier tfvars

Pour les modules racines, fournissez les variables en utilisant un fichier de variables .tfvars. Par souci de cohérence, nommez vos fichiers de variables terraform.tfvars.

Ne spécifiez pas de variables en utilisant d'autres options de ligne de commande var-files ou var='key=val'. Les options de ligne de commande sont éphémères et s'oublient facilement. L'utilisation d'un fichier de variables par défaut est plus prévisible.

Enregistrer le fichier .terraform.lock.hcl

Pour les modules racine, le fichier de verrou de dépendance .terraform.lock.hcl doit être enregistré dans le contrôle de source. Cela vous permet de suivre et d'examiner les modifications apportées aux fournisseurs pour une configuration donnée.

Étapes suivantes