It’s 9 AM on a Tuesday. You, a reasonably caffeinated engineer, open a pull request to add a single tag to an S3 bucket. A one-line change. You run terraform plan and watch in horror as your screen scrolls with a novel’s worth of green, yellow, and red text. Two hundred and seventeen resources want to be updated.
Welcome to a special kind of archaeological dig. Somewhere, buried three folders deep, a “reusable” module you haven’t touched in six months has decided to redecorate your entire production environment. The brochure promised elegance and standards. The reality is a Tuesday spent doing debugging, cardio, and praying to the Git gods.
Small teams, in particular, fall into this trap. You don’t need to build a glorious cathedral of abstractions just to hang a picture on the wall. You need a hammer, a nail, and enough daylight to see what you’re doing.
The allure of the perfect system
Let’s be honest, custom Terraform modules are seductive. They whisper sweet nothings in your ear about the gospel of DRY (Don’t Repeat Yourself). They promise a future where every resource is a perfect, standardized snowflake, lovingly stamped out from a single, blessed template. It’s the engineering equivalent of having a perfectly organized spice rack where all the labels face forward.
In theory, it’s beautiful. In practice, for a small, fast-moving team, it’s a tax. A heavy one. An indirection tax.
What starts as a neat wrapper today becomes a Matryoshka doll of complexity by next quarter. Inputs multiply. Defaults are buried deeper than state secrets. Soon, flipping a single boolean in a variables.tf file feels like rewiring a nuclear submarine with the lights off. The module is no longer serving you; you are now its humble servant.
It’s like buying one of those hyper-specific kitchen gadgets, like a banana slicer. Yes, it slices bananas. Perfectly. But now you own a piece of plastic whose only job is to do something a knife you already owned could do just fine. That universal S3 module you built is the junk drawer of your infrastructure. Sure, it holds everything, but now you have to rummage past a broken can opener and three instruction manuals just to find a spoon.
A heuristic for staying sane
So, what’s the alternative? Anarchy? Copy-pasting HCL like a digital barbarian? Yes. Sort of.
Here’s a simple, sanity-preserving heuristic:
Duplicate once without shame. Duplicate twice with comments. On the third time, and only then, consider extracting a module.
Until you hit that third, clear, undeniable repetition of a pattern, plain HCL is your best friend. It wins on speed, clarity, and keeping the blast radius of any change predictably small. You avoid abstracting a solution before you even fully understand the problem.
Let’s see it in action. You need a simple, private S3 bucket for your new service.
The cathedral-builder’s approach might look like this:
# service-alpha/main.tf
module "service_alpha_bucket" {
source = "git::ssh://git@github.com/your-org/terraform-modules.git//s3/private-bucket?ref=v1.4.2"
bucket_name = "service-alpha-data-logs-2025"
enable_versioning = true
force_destroy = false # Safety first!
lifecycle_days = 90
tags = {
Service = "alpha"
ManagedBy = "Terraform"
}
}It looks clean, but what happens when you need to add a specific replication rule? Or a weird CORS policy for a one-off integration? You’re off to another repository to wage war with the module’s maintainer (who is probably you, from six months ago).
Now, the boring, sane, ship-it-today approach:
# service-alpha/main.tf
resource "aws_s3_bucket" "data_bucket" {
bucket = "service-alpha-data-logs-2025"
tags = {
Service = "alpha"
ManagedBy = "Terraform"
}
}
resource "aws_s3_bucket_versioning" "data_bucket_versioning" {
bucket = aws_s3_bucket.data_bucket.id
versioning_configuration {
status = "Enabled"
}
}
resource "aws_s3_bucket_lifecycle_configuration" "data_bucket_lifecycle" {
bucket = aws_s3_bucket.data_bucket.id
rule {
id = "log-expiration"
status = "Enabled"
expiration {
days = 90
}
}
}
resource "aws_s3_bucket_public_access_block" "data_bucket_access" {
bucket = aws_s3_bucket.data_bucket.id
block_public_acls = true
block_public_policy = true
ignore_public_acls = true
restrict_public_buckets = true
}Is it more lines of code? Yes. Is it gloriously, beautifully, and unapologetically obvious? Absolutely. You can read it, understand it, and change it in thirty seconds. No context switching. No spelunking through another codebase. Just a bucket, doing bucket things.
Where a module is not a swear word
Okay, I’m not a total monster. Modules have their place. They are the right tool when you are building the foundations, not the furniture.
A module earns its keep when it defines a stable, slow-moving, and genuinely complex pattern that you truly want to be identical everywhere. Think of it like the plumbing and electrical wiring of a house. You don’t reinvent it for every room.
Good candidates for a module include:
- VPC and core networking: The highway system of your cloud. Build it once, build it well, and then leave it alone.
- Kubernetes cluster baselines: The core EKS/GKE/AKS setup, IAM roles, and node group configurations.
- Security and telemetry agents: The non-negotiable stuff that absolutely must run on every single instance.
- IAM roles for CI/CD: A standardized way for your deployment pipeline to get the permissions it needs.
The key difference? These things change on a scale of months or years, not days or weeks.
Your escape plan from module purgatory
What if you’re reading this and nodding along in despair, already trapped in a gilded cage of your own abstractions? Don’t panic. There’s a way out, and it doesn’t require a six-month migration project.
- Freeze everything: First, go to every service that uses the problematic module and pin the version number. ref=v1.4.2. No more floating on main. You’ve just stopped the bleeding.
- Take inventory: In one service, run a Terraform state list to see the exact resources managed by the module.
- Perform the adoption: This is the magic trick. Write the plain HCL code for those resources directly in your service’s configuration. Then, tell Terraform that the old resource (inside the module) and your new resource (the plain HCL) are actually the same thing. You do this with a moved block or the Terraform state mv command.
Let’s say your module created a bucket. The state address is module.service_alpha_bucket.aws_s3_bucket.this[0]. Your new plain resource is aws_s3_bucket.data_bucket.
You would run:
terraform state mv 'module.service_alpha_bucket.aws_s3_bucket.this[0]' aws_s3_bucket.data_bucket- Verify and obliterate: Run terraform plan. It should come back with “No changes. Your infrastructure matches the configuration.” The plan is clean. You are now free. Delete the module block, pop the champagne, and submit your PR. Repeat for other services, one at a time. No heroics.
Fielding objections from the back row
When you propose this radical act of simplicity, someone will inevitably raise their hand.
- “But we need standards!” You absolutely do. Standardize on things that matter: tags, naming conventions, and security policies. Enforce them with tools like tflint, checkov, and OPA/Gatekeeper. A linter yelling at you in a PR is infinitely better than a module silently deploying the wrong thing everywhere.
- “What about junior developers? They need a paved road!” They do. A haunted mega-module with 50 input variables is not a paved road; it’s a labyrinth with a minotaur. A better “paved road” is a folder of well-documented, copy-pasteable examples of plain HCL for common tasks.
- “Compliance will have questions!” Good. Let them. A tiny, focused, version-pinned module for your IAM boundary policy is a fantastic answer. A sprawling, do-everything wrapper module that changes every week is a compliance nightmare waiting to happen.
The gospel of ‘Good Enough’ for now
Stop trying to solve tomorrow’s problems today. That perfect, infinitely configurable abstraction you’re dreaming of is a solution in search of a problem you don’t have yet.
Don’t optimize for DRY. Optimize for change.
Small teams don’t need fewer lines of HCL; they need fewer places to look when something breaks at 3 PM on a Friday. They need clarity, not cleverness. Keep your power tools for the heavy-duty work. Save the cathedral for when you’ve actually founded a religion.
For now, ship the bucket, and go get lunch.
