Gruntwork Blog | DevOps Field Guide: Your Infrastructure Repo Is a Mess (Here's How to Fix It)
Platform
Open Source
PricingResources
Sign In
Book a demo
Back to Blog
DevOps
DevOps Field Guide: Your Infrastructure Repo Is a Mess (Here's How to Fix It)
Brian<br>Torres
DevOps Solutions Engineer<br>May 19, 2026
NOTE: This guide is specifically about structuring Terragrunt repos for OpenTofu or Terraform. The patterns below rely on Terragrunt features such as hierarchical configuration, inherited settings, generated provider/backend files, and Stacks. They will not work the same way in stock OpenTofu or Terraform unless you add Terragrunt or build equivalent conventions yourself.<br>Infrastructure repos are prone to fall apart over time, but it almost never happens all at once. Instead, they decay over time because of inconsistent structure, policy, and behaviors. Decisions that felt right on day 1 can become large problems by day 100. A lack of good hygiene and best practices mean the proverbial “day 100” can come at any time. Let’s talk about why.<br>Every team sets up their repo the same way: a single OpenTofu/Terraform file, a few resources, and often a terraform.tfvars. It works, it’s clean, and it feels good. Then you add a second environment. Then a third. Then someone copies the prod folder to create staging, changes two values, and forgets to update a third. Six months later, you're drowning in duplicated configuration, terrified to change anything because you can't tell what's shared and what's diverged.<br>We’ve seen this pattern across teams running everything from a handful of AWS accounts to hundreds. In most cases, the problem wasn’t tooling. It was structure and setup.<br>We’ve helped teams unwind this without rewriting everything. The solution is not more scripts or more modules. It’s a repo that makes structure, ownership, and change boundaries obvious. (And don’t worry, this doesn’t have to be manual work.)<br>In this guide, we’re going to walk you through how a good repository is structured and what good repo hygiene looks like so you can model the behaviors and get rid of the firefighting you’re probably dealing with.<br>The Failure Modes<br>Bad repos tend to fall into a few categories:<br>The Copy-Paste Problem<br>The Mega-Module Monolith<br>The Tribal Knowledge Trap<br>There are others, though they are less common.<br>The Copy-Paste Problem<br>This anti-pattern is the one we alluded to in the intro. It is the most common problem we see IaC teams run into. When you need a new environment, you duplicate an existing folder and tweak a few values. Now you have two copies of everything to keep in sync. When you fix a bug in one, you have to remember to fix it in the other. Multiply that across five environments and three regions, and you're managing 15 copies of the same VPC configuration.<br>The Mega-Module Monolith<br>Some teams think they know better than to copy-paste, so they go the opposite direction. They build one enormous module that deploys everything: networking, compute, databases, DNS, IAM. It takes 45 minutes to plan and requires 200 input variables. Nobody understands all of it. Nobody wants to touch it. And everybody depends on it working.<br>Until that day comes along when someone needs to change a security group that requires a plan against your entire infrastructure. Now your module is a liability.<br>The Tribal Knowledge Trap<br>Legend has it that someone who worked here a few years ago wrote a script that has to run before every terragrunt apply. Nobody knows why and there’s no reason to question it.<br>Or there’s that one resource that must be created manually, or that a bootstrap step lives in a wiki page nobody has opened in a year. When you’re dealing with tribal knowledge, the repository takes a back seat to the truth.
Problem<br>What fixes it
Copy-paste environments<br>Inheritance + stacks
Drift between envs<br>Shared config + version pinning
Risky changes<br>Small state + stacks
Hidden behavior<br>CI/CD-only deploys
What a Good Infrastructure Repo Optimizes For<br>A good infrastructure repo is organized so it makes the correct change obvious.<br>When an engineer opens a repo, they should be able to answer four questions quickly:<br>Where does this resource live?<br>What config is shared versus environment-specific?<br>What depends on what?<br>How does this get deployed safely?<br>That means the repository should optimize for a few practical outcomes:<br>Clear location: Every piece of infrastructure has one obvious home.<br>Minimal duplication: Shared configuration is defined once, then inherited.<br>Small blast radius: Changes affect only the unit they are supposed to affect.<br>Reviewable differences: When prod and staging differ, the diff should be visible and intentional.<br>Reproducibility: Deployment should come from code and pipeline, not memory.<br>A well-structured infrastructure repository solves all of these problems. Most teams that scale this pattern also separate live configuration from reusable modules. (We’ll come back to that later.) Here's the...