Managing infrastructure at scale is a complex endeavor that demands meticulous planning, robust tooling, and continuous adaptation. Two structural challenges appear consistently in organizations that have grown beyond a single team managing a single environment: the tension between monorepo and multi-repo architectures, and the difficulty of keeping Terraform modules consistent across the teams that consume them. Neither has a simple answer, but both have well-understood approaches that reduce the friction significantly.
Balancing Monorepos and Multi-Repo Architectures
The Core Tension
A monorepo for infrastructure gives you everything in one place: a single history, a single access control model, and a single CI/CD pipeline to maintain. As long as the organization is small and the infrastructure is relatively flat, it works well. The problems emerge at scale—when dozens of teams are committing to the same repository, when CI runs take twenty minutes because the pipeline processes the entire codebase for every change, and when a mistake in one team's module can block deployments across the organization.
Multi-repo architectures solve the coordination problem by distributing ownership. Each team or domain manages its own repository, moves at its own pace, and isn't affected by changes in unrelated parts of the infrastructure. The cost is discoverability and consistency: foundational modules are harder to share, standards drift between repositories, and understanding the full infrastructure topology requires looking in many places.
Best Practices for a Hybrid Approach
The approach that works in most organizations at scale is neither pure monorepo nor pure multi-repo—it's a hybrid that preserves the benefits of centralization for shared infrastructure while giving individual teams autonomy over workload-specific code.
**Shared infrastructure in a central repository:** Foundational modules—networking, IAM, shared services, security baselines—live in a single repository owned by a platform team. Changes to these modules go through a structured review process with explicit versioning. Consuming teams reference modules from this registry by version, not by path.
**Workload infrastructure in team repositories:** Each team owns a repository for the infrastructure that supports their services. They consume shared modules as versioned dependencies. They control their own deployment pipelines and don't share a change queue with unrelated teams.
**Cross-cutting visibility:** A separate tooling layer—whether an internal platform portal or a commercial infrastructure management tool—maintains an inventory of all resources across all repositories. The separation of code ownership doesn't require accepting a fragmented view of the environment.
State Management
State management is one of the most consequential decisions in a multi-repo or hybrid architecture. A few principles reduce the risk of state-related incidents:
Tooling
Tools like Atlantis, Terragrunt, and Spacelift address different aspects of multi-repo management. Atlantis automates plan and apply workflows through pull request comments and works well for teams that want to keep control in their version control system. Terragrunt reduces configuration duplication across environments by providing a wrapper layer for Terraform that supports DRY patterns. Spacelift adds policy enforcement, drift detection, and approval workflows at the platform level. The right choice depends on where your current friction is—workflow automation, configuration duplication, or governance and visibility.
Ensuring Consistency with Module Versioning
The Versioning Problem
Infrastructure modules are shared libraries. When a security fix is applied to a networking module, it needs to reach every team consuming that module. When a breaking change is introduced—a required variable is added, a default is changed, a resource is renamed—consuming teams need to know before it breaks their pipelines.
Without a versioning discipline, module updates propagate unpredictably. Teams discover changes when their pipelines fail. Security fixes don't reach production because no one is tracking which teams are on which version. The platform team that maintains shared modules has no visibility into the upgrade state of their consumers.
Semantic Versioning
Semantic versioning—`MAJOR.MINOR.PATCH`—provides a shared vocabulary for communicating the nature of changes:
The value of this system depends entirely on consistent application. A module that increments MINOR for breaking changes, or that skips MAJOR versions because the breaking change "only affects edge cases," destroys the trust that makes consumers willing to adopt updates quickly.
Centralized Module Registries
A private Terraform registry—whether hosted in Terraform Cloud/Enterprise, a cloud provider's native registry, or an open-source alternative—provides a single place to publish, version, and document modules. Consuming teams reference modules by registry address and version constraint rather than by Git URL, which makes version management explicit and auditable.
The registry is also where documentation lives. A module entry that includes a README explaining the module's purpose, its inputs and outputs, its known limitations, and the operational context for its failure modes is worth significantly more than one that lists variables without context.
Parameterization and Flexibility
Modules that are too rigid get forked. When a module doesn't support a configuration that a team needs, the path of least resistance is copying the module into the team's own repository and modifying it—which immediately creates a divergence that will never be reconciled. The version in the team's repository won't receive the security fix. The breaking change in the shared module won't affect them, but neither will the bug fix.
Designing modules for parameterization—using variables with sensible defaults rather than hardcoded values, supporting optional features through conditional expressions, exposing outputs that allow consumers to extend the module's behavior without modifying it—reduces the incentive to fork. The goal is modules that cover the common cases well and make the uncommon cases possible, without requiring a fork for either.
Key Takeaways
The two problems described here—repository architecture and module versioning—are not independent. An organization with a well-structured hybrid repository architecture but no versioning discipline will still accumulate drift and security debt. An organization with rigorous semantic versioning but a monorepo that creates deployment bottlenecks will still find that teams resist adopting updates because the upgrade process is too painful.
The combination that works is: clear ownership boundaries enforced through repository structure, shared foundational infrastructure managed through a versioned registry, automated tooling that makes the right path the easy path, and visibility tooling that surfaces the state of module adoption across the organization without requiring manual tracking.
