Direct answer
A module is a packaged, reusable chunk of Terraform configuration that other teams can call like a library, rather than writing from scratch. Use a federated model: a small central platform team owns the module registry, the publish pipeline, and the guardrails, while module authors own correctness of their own modules and consuming teams own how they compose modules for their own environments. What keeps the platform team from becoming a bottleneck is that quality gets enforced by automation in the publish pipeline, not by a human reviewing every consumer's usage, and adoption gets driven by making the supported path the easiest path, not by mandate.
Structured elaboration
Ownership and governance
- Platform team: owns the module registry, the CI/CD primitives the publish pipeline runs on, and the core tier of modules.
- Module authors: own correctness, tests, and documentation for the specific module they publish.
- Consuming teams: own how they compose and pin modules for their own environment, and are responsible for staying within a supported version window.
- How contributions get reviewed and merged: a lightweight RFC (a short written proposal, reviewed async) is required for a new core module or a breaking change to an existing one; ordinary non-breaking changes to a module go through a normal PR requiring approval from that module's owning author plus an automated pass through the publish pipeline below, not a platform-team gatekeeper on every PR.
Module catalog and the publish pipeline
Every module change goes through the same automated sequence before it is available to consumers: lint and static checks, unit and terraform plan tests, an ephemeral integration apply (stand the module up for real in a disposable environment, then tear it down), a semver tag, and promotion to the stable channel.
mermaid
flowchart LR
A[Module change proposed] --> B[Lint and static checks]
B --> C[Unit and plan tests]
C --> D[Ephemeral integration apply]
D --> E[Semver tag]
E --> F[Promote to stable channel]
F --> G[Consumers pull pinned version]
Release cadence is explicit rather than ad hoc: patch and minor versions can ship as soon as they pass this pipeline, majors (anything breaking) are gated behind the RFC step above regardless of how fast the pipeline itself runs. Required CI testing before a release is not optional for any tier of module, core or community, it is the mechanism that lets the platform team not have to manually vet every change.
Repo topology for a large org
For an organization around 200 engineers, monorepo versus multi-repo for shared modules is a real trade-off, not a style preference:
- Monorepo: everyone sees the latest version of every module, cross-module refactors can be atomic, and discovery is trivial. At 200 engineers, CI complexity becomes the limiting factor: a naive "test everything on every change" setup does not scale, so this only works with path-based CI triggers and build caching, so a change to one module does not re-test the entire repo.
- Multi-repo: independent release cadence per module and cleaner ownership boundaries (a team owns their repo outright), but cross-module changes require coordinated version bumps across repos, and discovery depends on the registry actually being good, since there is no single place to browse.
- Migration path: moving an existing multi-repo org toward a monorepo, or vice versa, is done incrementally, module by module, behind the same registry interface, so consumers keep pinning versions from the registry throughout and never have to care which repo topology backs a given module on a given day.
Keeping quality and velocity up without a bottleneck
- Measuring adoption and detecting anti-patterns: the platform team tracks which modules and versions are actually in use across the org (via the registry's usage telemetry) and flags patterns like a team pinned three major versions behind, or a team that forked a module instead of contributing back, before they become an incident.
- Automated compatibility and regression checks in the registry: beyond the publish pipeline's own tests, the registry can run a new module version against a sample of real consumer configurations to catch a break before any consumer upgrades into it. This is meaningfully deeper staff-level territory than the basic publish pipeline, worth treating as its own follow-up.
Worked example: two concrete scenarios from this program
Consolidating duplicate modules. Say an audit turns up two dozen nearly-identical modules for "an S3 bucket with standard encryption and logging," written independently by different teams over time. The fix is not a mandate to stop; it is building one generic, well-designed replacement module, publishing it through the same pipeline above, and then gating the migration in CI: add a policy check (via terraform-compliance or a similar policy-as-code check in the plan stage) that fails any PR still referencing one of the deprecated modules past an announced sunset date, so consumers convert on their own schedule but the cutover cannot silently regress mid-migration. Adoption telemetry from the point above is what tells the platform team which teams still need outreach before that sunset date arrives.
Rolling out a breaking change. Say the owner of a widely-consumed networking module needs to add a new required variable and rename an output. Rolling that out without breaking every consumer at once looks like: publish it as a new major version behind the RFC and semver-tag process above, keep the previous major version available and supported in the registry for a defined deprecation window, and have the new major version emit both the old and new output names during that window, with the old one marked deprecated, so consumers can migrate their references before the old name is actually removed. A migration guide, and ideally a small codemod script, ships alongside the new major version; for the slow-moving teams still on the old major as the deprecation window closes, that is exactly the case the adoption-tracking telemetry above exists to surface, so the platform team can reach out before support actually ends rather than after something breaks.
Naming collisions. As the module catalog grows, IAM roles and S3 buckets created by different modules start colliding across environments and teams (two modules independently create a role named app-role in the same account). The fix is a naming convention enforced in code, not in a review checklist: a shared locals block computing a guaranteed-unique name from inputs every module is required to take, for example local.name_prefix = "${var.org}-${var.env}-${var.team}-${var.resource_name}", with a policy-as-code check in the publish pipeline that rejects any module publishing a resource name that does not derive from that convention, so a colliding name never gets past review because it never gets past the pipeline.
Trade-offs & pitfalls
- The platform team becomes a bottleneck exactly when it inserts itself as a required manual reviewer on every consumer PR; the fix is pushing enforcement into the automated pipeline (lint, tests, policy checks) so a human is only in the loop for genuinely new core modules or breaking changes via the RFC process.
- Under-governance (no naming convention, no compatibility checks) causes the naming-collision and breaking-change failures above; over-governance (requiring platform sign-off on routine changes) kills velocity and pushes teams to fork instead of contribute, which then shows up in the adoption telemetry as forked, unsupported modules.
- Monorepo CI complexity is a real cost, not a hypothetical one, at 200 engineers; if path-based triggers and caching are not in place from the start, the monorepo choice will get blamed for a tooling gap instead.
- Track PR cycle time, incidents per deploy that touch a shared module, and reuse rate of core modules over time; a program that is winning on adoption but losing on incident rate is not actually working yet.