Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Bonnes pratiques pour la structure et l'organisation de la base de code

Une structure et une organisation de base de code appropriées sont essentielles car l'utilisation de Terraform augmente au sein des grandes équipes et entreprises. Une base de code bien conçue permet une collaboration à grande échelle tout en améliorant la maintenabilité.

Cette section fournit des recommandations sur la modularité de Terraform, les conventions de dénomination, la documentation et les normes de codage qui favorisent la qualité et la cohérence.

Les conseils incluent la division de la configuration en modules réutilisables par environnement et par composant, l'établissement de conventions de dénomination à l'aide de préfixes et de suffixes, la documentation des modules et l'explication claire des entrées et des sorties, et l'application de règles de formatage cohérentes à l'aide de contrôles de style automatisés.

Les meilleures pratiques supplémentaires concernent l'organisation logique des modules et des ressources dans une hiérarchie structurée, le catalogage des modules publics et privés dans la documentation et l'extraction des détails de mise en œuvre inutiles dans les modules afin de simplifier l'utilisation.

En mettant en œuvre des directives relatives à la structure de base du code relatives à la modularité, à la documentation, aux normes et à l'organisation logique, vous pouvez favoriser une large collaboration entre les équipes tout en garantissant la maintenance de Terraform à mesure que l'utilisation se répand au sein de l'organisation. En appliquant les conventions et les normes, vous pouvez éviter la complexité d'une base de code fragmentée.

Implémenter une structure de référentiel standard

Nous vous recommandons d'implémenter la disposition de référentiel suivante. La normalisation de ces pratiques de cohérence entre les modules améliore la découvrabilité, la transparence, l'organisation et la fiabilité tout en permettant la réutilisation dans de nombreuses configurations Terraform.

Structure du module racine

Terraform s'exécute toujours dans le contexte d'un seul module racine. Une configuration Terraform complète comprend un module racine et l'arborescence des modules enfants (qui inclut les modules appelés par le module racine, tous les modules appelés par ces modules, etc.).

Exemple de base de la disposition du module racine Terraform :

.
├── data.tf
├── envs
│   ├── dev
│   │   └── terraform.tfvars
│   ├── prod
│   │   └── terraform.tfvars
│   └── test
│       └── terraform.tfvars
├── locals.tf
├── main.tf
├── outputs.tf
├── providers.tf
├── README.md
├── terraform.tfvars
├── variables.tf
└── versions.tf

Structure de module réutilisable

Les modules réutilisables suivent les mêmes concepts que les modules racines. Pour définir un module, créez un nouveau répertoire pour celui-ci et placez-y les .tf fichiers, comme vous définiriez un module racine. Terraform peut charger des modules soit à partir de chemins relatifs locaux, soit à partir de référentiels distants. Si vous vous attendez à ce qu'un module soit réutilisé par de nombreuses configurations, placez-le dans son propre référentiel de contrôle de version. Il est important de garder l'arborescence des modules relativement plate pour faciliter la réutilisation des modules dans différentes combinaisons.

Exemple de base de disposition de module réutilisable Terraform :

.
├── data.tf
├── examples
│   ├── multi-az-new-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── vpc.tf
│   └── single-az-existing-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   └── versions.tf
├── iam.tf
├── locals.tf
├── main.tf
├── outputs.tf
├── README.md
├── variables.tf
└── versions.tf

Structure pour la modularité

En principe, vous pouvez combiner toutes les ressources et autres constructions dans un module, mais l'utilisation excessive de modules imbriqués et réutilisables peut rendre votre configuration globale de Terraform plus difficile à comprendre et à maintenir. Utilisez donc ces modules avec modération.

Lorsque cela est logique, divisez votre configuration en modules réutilisables qui augmentent le niveau d'abstraction en décrivant un nouveau concept de votre architecture construit à partir de types de ressources.

Lorsque vous modularisez votre infrastructure en définitions réutilisables, privilégiez des ensembles logiques de ressources plutôt que des composants individuels ou des collections trop complexes.

N'encapsulez pas des ressources uniques

Vous ne devez pas créer de modules qui constituent des enveloppes fines autour d'autres types de ressources uniques. Si vous ne parvenez pas à trouver un nom différent du nom du type de ressource principal qu'il contient, votre module ne crée probablement pas de nouvelle abstraction, cela ajoute une complexité inutile. Utilisez plutôt le type de ressource directement dans le module d'appel.

Encapsuler les relations logiques

Regroupez des ensembles de ressources connexes telles que les bases du réseau, les niveaux de données, les contrôles de sécurité et les applications. Un module réutilisable doit encapsuler des éléments d'infrastructure qui fonctionnent ensemble pour activer une fonctionnalité.

Maintenir un héritage stable

Lorsque vous imbriquez des modules dans des sous-répertoires, évitez d'aller à plus d'un ou deux niveaux de profondeur. Les structures d'héritage profondément imbriquées compliquent les configurations et le dépannage. Les modules doivent s'appuyer sur d'autres modules, et non créer des tunnels à travers eux.

En concentrant les modules sur des groupements de ressources logiques qui représentent des modèles d'architecture, les équipes peuvent rapidement configurer des bases d'infrastructure fiables. Équilibrez l'abstraction sans suringénierie ou simplification.

Ressources de référence dans les sorties

Pour chaque ressource définie dans un module réutilisable, incluez au moins une sortie qui fait référence à la ressource. 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 commander correctement votre module par rapport à leurs configurations Terraform.

Des modules bien structurés qui assurent la cohérence de l'environnement, des regroupements axés sur des objectifs et des références de ressources exportées permettent une collaboration Terraform à grande échelle à l'échelle de l'organisation. Les équipes peuvent assembler l'infrastructure à partir de blocs de construction réutilisables.

Ne configurez pas les fournisseurs

Bien que les modules partagés héritent des fournisseurs des modules appelants, les modules ne doivent pas configurer eux-mêmes les paramètres des fournisseurs. Évitez de spécifier des blocs de configuration du fournisseur dans les modules. Cette configuration ne doit être déclarée qu'une seule fois globalement.

Déclarer les fournisseurs requis

Bien que les configurations des fournisseurs soient partagées entre les modules, les modules partagés doivent également déclarer leurs propres exigences en matière de fournisseur. Cette pratique permet à Terraform de s'assurer qu'il existe une seule version du fournisseur compatible avec tous les modules de la configuration et de spécifier l'adresse source qui sert d'identifiant global (indépendant du module) au fournisseur. Cependant, les exigences du fournisseur spécifiques au module ne spécifient aucun des paramètres de configuration qui déterminent les points de terminaison distants auxquels le fournisseur aura accès, tels qu'un. Région AWS

En déclarant les exigences de version et en évitant la configuration codée en dur des fournisseurs, les modules assurent la portabilité et la réutilisabilité entre les configurations Terraform à l'aide de fournisseurs partagés.

Pour les modules partagés, définissez les versions de fournisseur minimales requises dans un bloc required_providers dans. versions.tf

Pour déclarer qu'un module nécessite une version particulière du AWS fournisseur, utilisez un required_providers bloc à l'intérieur d'un terraform bloc :

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0.0"
    }
  }
}

Si un module partagé ne prend en charge qu'une version spécifique du AWS fournisseur, utilisez l'opérateur de contrainte pessimiste (~>), qui autorise uniquement l'incrémentation du composant de version le plus à droite :

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

Dans cet exemple, ~> 4.0 autorise l'installation de 4.57.1 et 4.67.0 mais non5.0.0. Pour plus d'informations, consultez la section Syntaxe des contraintes de version dans la HashiCorp documentation.

Respectez les conventions de dénomination

Des noms clairs et descriptifs simplifient votre compréhension des relations entre les ressources du module et l'objectif des valeurs de configuration. La cohérence avec les directives de style améliore la lisibilité tant pour les utilisateurs du module que pour les responsables de la maintenance.

Suivez les directives relatives à la dénomination des ressources

Suivez les directives relatives à la dénomination des variables

Utiliser les ressources relatives aux pièces jointes

Certaines ressources contiennent des pseudo-ressources intégrées sous forme d'attributs. Dans la mesure du possible, évitez d'utiliser ces attributs de ressource intégrés et utilisez plutôt la ressource unique pour associer cette pseudo-ressource. Ces relations entre les ressources peuvent entraîner des cause-and-effect problèmes propres à chaque ressource.

En utilisant un attribut intégré (évitez ce modèle) :

resource "aws_security_group" "allow_tls" {
  ...
  ingress {
    description      = "TLS from VPC"
    from_port        = 443
    to_port          = 443
    protocol         = "tcp"
    cidr_blocks      = [aws_vpc.main.cidr_block]
    ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

Utilisation des ressources de pièces jointes (de préférence) :

resource "aws_security_group" "allow_tls" {
  ...
}

resource "aws_security_group_rule" "example" {
  type              = "ingress"
  description      = "TLS from VPC"
  from_port        = 443
  to_port          = 443
  protocol         = "tcp"
  cidr_blocks      = [aws_vpc.main.cidr_block]
  ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  security_group_id = aws_security_group.allow_tls.id
}

Utiliser les balises par défaut

Attribuez des balises à toutes les ressources qui peuvent accepter des balises. Le AWS fournisseur Terraform dispose d'une source de données aws_default_tags que vous devez utiliser dans le module racine.

Envisagez d'ajouter les balises nécessaires à toutes les ressources créées par un module Terraform. Voici une liste des balises que vous pouvez associer :

Répondez aux exigences du registre Terraform

Un référentiel de modules doit répondre à toutes les exigences suivantes pour pouvoir être publié dans un registre Terraform.

Vous devez toujours respecter ces exigences, même si vous ne prévoyez pas de publier le module dans un registre à court terme. Ce faisant, vous pouvez publier le module dans un registre ultérieurement sans avoir à modifier la configuration et la structure du référentiel.

Pour plus d'informations, consultez Préparation d'un référentiel de modules dans la documentation Terraform.

Utiliser les sources de modules recommandées

Terraform utilise l'sourceargument d'un bloc de module pour rechercher et télécharger le code source d'un module enfant.

Nous vous recommandons d'utiliser des chemins locaux pour les modules étroitement liés dont l'objectif principal est de factoriser les éléments de code répétés, et d'utiliser un registre de modules Terraform natif ou un fournisseur VCS pour les modules destinés à être partagés par plusieurs configurations.

Les exemples suivants illustrent les types de sources les plus courants et les plus recommandés pour le partage de modules. Les modules de registre prennent en charge le versionnement. Vous devez toujours fournir une version spécifique, comme indiqué dans les exemples suivants.

Registre

Registre Terraform :

module "lambda" {
  source = "github.com/terraform-aws-modules/terraform-aws-lambda.git?ref=e78cdf1f82944897ca6e30d6489f43cf24539374" #--> v4.18.0

  ...

}

En épinglant les hachages de validation, vous pouvez éviter de dériver des registres publics vulnérables aux attaques de la chaîne d'approvisionnement.

HCP Terraform :

module "eks_karpenter" {
  source = "app.terraform.io/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Terraform Entreprise :

module "eks_karpenter" {
  source = "terraform.mydomain.com/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Fournisseurs de VCS

Les fournisseurs de VCS soutiennent l'refargument en faveur de la sélection d'une révision spécifique, comme le montrent les exemples suivants.

GitHub (HTTPS) :

module "eks_karpenter" {
  source = "github.com/my-org/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Dépôt Git générique (HTTPS) :

module "eks_karpenter" {
  source = "git::https://example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Dépôt Git générique (SSH) :

module "eks_karpenter" {
  source = "git::ssh://username@example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Respectez les normes de codage

Appliquez des règles et des styles de formatage Terraform cohérents à tous les fichiers de configuration. Appliquez les normes en utilisant des contrôles de style automatisés dans les pipelines CI/CD. Lorsque vous intégrez les meilleures pratiques de codage dans les flux de travail d'équipe, les configurations restent lisibles, maintenables et collaboratives, car leur utilisation se répand largement au sein de l'organisation.

Suivez les directives de style

Configurer les hooks de pré-validation

Configurez des hooks de pré-validation côté client qui exécutentterraform fmt, tflintcheckov, et d'autres analyses de code et vérifications de style avant d'autoriser les validations. Cette pratique vous permet de valider la conformité aux normes plus tôt dans les flux de travail des développeurs.

Utilisez des frameworks de pré-validation tels que le pré-commit pour ajouter le linting, le formatage et le scan de code Terraform comme points d'ancrage sur votre machine locale. Les hooks s'exécutent à chaque validation Git et échouent si les vérifications ne sont pas validées.

Le transfert des contrôles de style et de qualité vers des hooks de pré-validation locaux fournit un feedback rapide aux développeurs avant l'introduction des modifications. Les normes font partie du flux de travail de codage.