Bonnes pratiques pour les modules réutilisables

Ce document fournit des consignes et des recommandations à prendre en compte lors de l'utilisation de modules Terraform réutilisables.

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.

Activer les API requises dans les modules

Les modules Terraform peuvent activer tous les services requis en utilisant la ressource google_project_service ou le module project_services. Inclure l'activation des API facilite les démonstrations.

  • Si l'activation d'une API est incluse dans un module, elle doit pouvoir être désactivée en exposant une variable enable_apis dont la valeur par défaut est true.

  • Si l'activation d'une API est incluse dans un module, elle doit définir disable_services_on_destroy sur false, car cet attribut peut poser des problèmes lorsque vous utilisez plusieurs instances du module.

    Exemple :

    module "project-services" {
  source  = "terraform-google-modules/project-factory/google//modules/project_services"
  version = "~> 12.0"

  project_id  = var.project_id
  enable_apis = var.enable_apis

  activate_apis = [
    "compute.googleapis.com",
    "pubsub.googleapis.com",
  ]
  disable_services_on_destroy = false
}

Inclure un fichier de propriétaires

Pour tous les modules partagés, incluez un fichier OWNERS (ou CODEOWNERS sur GitHub), qui indique qui est responsable du module. Avant toute demande d'extraction, un propriétaire doit l'approuver.

Publier des versions avec tags

Parfois, des modules nécessitent des modifications destructives et vous devez communiquer les effets aux utilisateurs afin qu'ils puissent rattacher leurs configurations à une version spécifique.

Assurez-vous que les modules partagés suivent SemVer 2.0.0 lorsque de nouvelles versions sont taguées ou publiées.

Lorsque vous référencez un module, utilisez une contrainte de version pour rattacher la version majeure. Exemple :

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 20.0"
}

Ne pas configurer de fournisseurs ou de backends.

Les modules partagés ne doivent pas configurer de fournisseurs ou de backends. Configurez plutôt les fournisseurs et les backends dans les modules racine.

Pour les modules partagés, définissez les versions minimales requises du fournisseur dans un bloc required_providers, comme suit :

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

Sauf indication contraire, supposez que les nouvelles versions du fournisseur fonctionneront normalement.

Exposer les libellés en tant que variable

Permet une flexibilité dans l'ajout de libellés aux ressources via l'interface du module. Envisagez de fournir une variable labels avec un mappage vide comme valeur par défaut :

variable "labels" {
  description = "A map of labels to apply to contained resources."
  default     = {}
  type        = "map"
}

Exposer les sorties de toutes les ressources

Les variables et les sorties vous permettent de déduire les dépendances entre les modules et les ressources. Sans aucune sortie, les utilisateurs ne peuvent pas trier correctement votre module en fonction de leurs configurations Terraform.

Pour chaque ressource définie dans un module partagé, incluez au moins une sortie qui référence la ressource.

Utiliser des sous-modules intégrés pour les logiques complexes

  • Les modules intégrés vous permettent d'organiser des modules Terraform complexes en unités plus petites et de dédupliquer les ressources communes.
  • Placez les modules intégrés dans modules/$modulename.
  • Traitez les modules intégrés comme privés, ne devant pas être utilisés par des modules externes, sauf indication contraire dans la documentation du module partagé.
  • Terraform ne suit pas les ressources refactorisées. Si vous commencez avec plusieurs ressources dans le module de premier niveau, puis que vous les transférez dans des sous-modules, Terraform tente de recréer toutes les ressources refactorisées. Pour atténuer ce comportement, utilisez des blocs moved lors de la refactorisation.
  • Les sorties définies par les modules internes ne sont pas automatiquement exposées. Pour partager les sorties des modules internes, réexportez-les.

Étapes suivantes