Monorepo vs un repo par stack Terraform

Le choix entre un monorepo (tout dans un seul dépôt Git) et un repo par stack (un dépôt par composant d’infrastructure) dépend de la taille de l’équipe et du couplage entre les composants. En résumé : commencez par un monorepo, séparez quand les équipes ou les cycles de déploiement divergent.

Prérequis : avoir lu Séparer dev, staging et prod et Organiser un dépôt Terraform pour comprendre la structure interne d’un projet.

Ce que vous allez apprendre

Distinguer les deux stratégies et leurs variantes
Identifier les critères de décision (taille d’équipe, couplage, autonomie)
Choisir l’approche adaptée à votre contexte
Anticiper les problèmes de chaque approche à grande échelle

Le monorepo : tout au même endroit

Un seul dépôt Git contient l’ensemble des configurations Terraform :

infra/
├── modules/
│   ├── reseau/
│   ├── compute/
│   └── monitoring/
├── stacks/
│   ├── plateforme/
│   │   ├── envs/
│   │   │   ├── dev/
│   │   │   └── prod/
│   ├── applicatif/
│   │   ├── envs/
│   │   │   ├── dev/
│   │   │   └── prod/
│   └── observabilite/
│       ├── envs/
│       │   ├── dev/
│       │   └── prod/
└── .gitignore

Les avantages

Visibilité globale — un git clone suffit pour voir toute l’infrastructure. Les nouveaux arrivants découvrent l’ensemble du système en un seul endroit.

Refactoring facilité — renommer un module, modifier une interface : un seul commit met à jour les modules et tous leurs appelants. Pas besoin de synchroniser plusieurs dépôts.

Modules locaux immédiats — le chemin relatif source = "../../modules/reseau" fonctionne directement. Pas de registre, pas de versionnement de modules à gérer.

Pipeline CI/CD unique — un seul fichier de configuration CI/CD déclare les pipelines de déploiement pour toutes les stacks.

Les inconvénients

Blast radius élevé — une erreur dans un module commun peut casser toutes les stacks en même temps. Un merge malencontreux dans modules/reseau/ impacte potentiellement plateforme, applicatif et observabilité.

Permissions granulaires difficiles — Git ne permet pas nativement de restreindre l’accès à un sous-répertoire. Toute l’équipe a accès à tout le code, y compris les stacks critiques comme la production.

Pipeline lent à grande échelle — chaque commit déclenche potentiellement des plan sur toutes les stacks, même celles non concernées. Il faut mettre en place de la détection de changements (changed files filter) pour éviter cela.

Conflits de merge fréquents — quand 10 personnes modifient le même dépôt en parallèle, les conflits sur les modules communs se multiplient.

Le multi-repo : un dépôt par stack

Chaque composant d’infrastructure a son propre dépôt Git :

# Dépôt 1 : infra-modules
modules/
├── reseau/
├── compute/
└── monitoring/

# Dépôt 2 : infra-plateforme
stacks/
└── plateforme/
    ├── envs/
    │   ├── dev/
    │   └── prod/

# Dépôt 3 : infra-applicatif
stacks/
└── applicatif/
    ├── envs/
    │   ├── dev/
    │   └── prod/

Les avantages

Isolation des permissions — chaque dépôt a ses propres accès. L’équipe applicatif n’a pas accès au dépôt plateforme et inversement.

Cycles de déploiement indépendants — une stack peut évoluer à son rythme sans attendre les autres. L’équipe observabilité déploie ses dashboards sans bloquer l’équipe réseau.

Blast radius limité — une erreur ne touche qu’un seul dépôt. Un merge cassé dans infra-applicatif ne met pas en danger la plateforme.

Pipelines rapides — chaque dépôt ne déclenche que son propre pipeline. Pas de détection de changements à configurer.

Les inconvénients

Versionnement des modules — les modules partagés doivent être publiés dans un registre (Terraform Registry privé, Git tags, S3) et versionnés. Chaque consommateur doit mettre à jour explicitement la version :

module "reseau" {
  source  = "git::https://gitlab.example.com/infra-modules.git//reseau?ref=v1.3.0"
}

Synchronisation difficile — un changement d’interface dans un module nécessite : (1) modifier le module, (2) publier une nouvelle version, (3) mettre à jour chaque consommateur dans son propre dépôt. Trois dépôts à toucher au lieu d’un seul commit.

Découverte fragmentée — un nouveau dans l’équipe doit cloner plusieurs dépôts pour comprendre l’ensemble. La vue globale se perd.

Duplication — sans discipline, chaque dépôt finit par dupliquer des configurations communes (providers, backend, CI/CD) au lieu de les partager.

L’arbre de décision

Critère	Monorepo	Multi-repo
Taille de l’équipe	1–8 personnes	8+ personnes ou multi-équipes
Couplage entre stacks	Fort (dépendances croisées)	Faible (stacks indépendantes)
Besoin de permissions par stack	Non	Oui
Cycles de déploiement	Synchronisés	Indépendants
Modules partagés	Beaucoup, en évolution	Stables, versionnés
Complexité CI/CD acceptable	Filtrage par changements	Simple (1 dépôt = 1 pipeline)

L’approche hybride

La plupart des projets en croissance adoptent une approche hybride :

Un dépôt pour les modules (versionnés avec des tags Git)
Un dépôt par stack (ou par équipe responsable)

# Dépôt : terraform-modules (source de vérité)
modules/
├── reseau/       ← tag v1.2.0
├── compute/      ← tag v2.0.1
└── monitoring/   ← tag v1.0.0

# Dépôt : infra-team-plateforme
envs/
├── dev/
│   └── main.tf   ← source = "git::...//reseau?ref=v1.2.0"
└── prod/
    └── main.tf   ← source = "git::...//reseau?ref=v1.1.0"  (version différente)

L’avantage : la prod peut rester sur une version stable d’un module pendant que dev teste la nouvelle version. Chaque équipe contrôle quand elle adopte les mises à jour.

Dépannage

Symptôme	Cause probable	Solution
”Tout le monde touche à tout”	Pas de convention CODEOWNERS	Ajouter un fichier CODEOWNERS pour attribuer des responsables par répertoire
Pipeline CI/CD trop lent (monorepo)	Tous les plans lancés à chaque commit	Filtrer par chemins modifiés (`changes:` en GitLab CI, `paths:` en GitHub Actions)
Version de module obsolète (multi-repo)	Pas de mise à jour automatique	Utiliser Renovate/Dependabot pour les sources de modules
Duplication de configuration (multi-repo)	Backend, providers copiés-collés partout	Factoriser dans un template de dépôt (repo template)

À retenir

Le monorepo est le bon point de départ : simple, visible, refactoring facile
Le multi-repo se justifie quand les équipes ont besoin d’autonomie et de permissions distinctes
Le signal pour migrer : les cycles de déploiement divergent entre les stacks
L’approche hybride (modules versionnés + un dépôt par stack) est le compromis le plus courant en entreprise
Le choix est organisationnel, pas technique — la taille de l’équipe est le critère principal

Prochaines étapes

Organiser un dépôt Terraform Conventions de fichiers standard à appliquer dans chaque dépôt.

Séparer dev, staging et prod La stratégie répertoires séparés avec module commun.

Les workspaces Terraform Comprendre le mécanisme workspace avant de choisir une stratégie.