{"id":198,"date":"2026-08-13T16:00:00","date_gmt":"2026-08-13T13:00:00","guid":{"rendered":"https:\/\/john-nessime.com\/blog\/?p=198"},"modified":"2026-08-06T17:19:39","modified_gmt":"2026-08-06T14:19:39","slug":"reusable-terraform-modules","status":"publish","type":"post","link":"https:\/\/john-nessime.com\/blog\/devops\/reusable-terraform-modules\/","title":{"rendered":"Terraform Modules Worth Reusing (And the Ones That Cost You)"},"content":{"rendered":"\n

The pull request was tiny. A module version bump, one line, nothing else in the diff. Then the plan came back with something nobody wants to read late on a Thursday: the RDS instance must be replaced<\/em>.<\/p>\n\n\n\n

Nothing about the database had changed. Same engine, same instance class, same subnet group. What changed was the resource’s name inside the module. The author had tidied up a resource \"aws_db_instance\" \"this\"<\/code> into something more descriptive, shipped it as a minor release, and moved on. Terraform saw a resource at an address that no longer existed and a resource at an address that did not exist before. Its default reading of that is destroy and create.<\/p>\n\n\n\n

That is the real cost of a module, and it is invisible on day one. The first apply is always fine. Modules feel great the week you adopt them. The bill arrives at the third upgrade, when the person who wrote it has moved teams and a dozen repositories consume it.<\/p>\n\n\n\n

This post is about judging that cost before you pay it. What separates reusable Terraform modules that are genuinely worth adopting from the ones your team quietly pins at an old version and refuses to touch, how to make your own modules land on the right side of that line, and what to do when a plan comes back looking like the one above.<\/p>\n\n\n\n

The bill for a module arrives at upgrade time<\/h2>\n\n\n\n

Terraform correlates state to configuration by address. Not by tags, not by cloud resource ID, not by anything the provider knows. Just the address: module.database.aws_db_instance.this<\/code>. Change any part of that path and, unless you say otherwise, Terraform concludes the old object should go and a new one should take its place.<\/p>\n\n\n\n

For a security group that is an annoyance. For a database, an object store, or anything holding data, it is an incident with a retro attached.<\/p>\n\n\n\n

The fix has existed for a long time and it is genuinely good: the moved<\/code> block. A module author who renames something declares the rename in code, ships it with the release, and every consumer’s next plan updates state instead of destroying infrastructure.<\/p>\n\n\n\n

# Shipped inside the module, in the same release as the rename.\n# Terraform rewrites the state address instead of planning a replacement.\n\nmoved {\n  from = aws_db_instance.this\n  to   = aws_db_instance.primary\n}<\/code><\/pre>\n\n\n\n
The block is declarative and it chains. If a resource moves in one release and moves again two releases later, someone jumping several versions at once still lands correctly, because Terraform resolves the whole chain. That is why a module that keeps its moved<\/code> blocks around is doing you a favour, and why one that strips them out after a release or two is quietly making every skipped upgrade riskier.<\/p>\n\n\n\n
So here is the whole thesis, and everything below is elaboration: a module is worth reusing if the next version bump is cheap. Everything else is secondary.<\/strong><\/p>\n\n\n\n
Five signals that reusable Terraform modules are worth adopting<\/h2>\n\n\n\n
These are the things I actually check before letting a module into a codebase. None of them take more than a few minutes. All of them predict the upgrade experience better than star counts do.<\/p>\n\n\n\n
1. It keeps state addresses stable, or tells you when it does not<\/h3>\n\n\n\n
Open the repository. Search for moved<\/code>. Read the changelog for the last major release and see whether renames are called out.<\/p>\n\n\n\n
A module with no moved<\/code> blocks and no changelog is not necessarily bad code. It just means every internal refactor becomes your problem, discovered in a plan output, usually under time pressure. A module that says “v3.0 renames the launch template resource, here are the moved blocks” is telling you it has thought about consumers.<\/p>\n\n\n\n
2. The input surface is narrow and typed<\/h3>\n\n\n\n
Count the variables. If a module needs forty inputs to cover its use cases, the abstraction was drawn in the wrong place. Usually that means two patterns got merged into one module because they looked similar from a distance.<\/p>\n\n\n\n
Width is not the only tell. Look at how the inputs are typed. A module that takes twelve loose strings is very different from one that takes three typed objects with sensible defaults baked in.<\/p>\n\n\n\n
variable \"logging\" {\n  description = \"Access log settings. Set to null to disable logging.\"\n  type = object({\n    bucket         = string\n    prefix         = optional(string, \"logs\/\")\n    retention_days = optional(number, 30)\n  })\n  default = null\n}\n\nvariable \"environment\" {\n  description = \"Deployment environment.\"\n  type        = string\n  nullable    = false\n\n  validation {\n    condition     = contains([\"dev\", \"staging\", \"prod\"], var.environment)\n    error_message = \"environment must be one of dev, staging or prod.\"\n  }\n}<\/code><\/pre>\n\n\n\n
Three things are doing work there. optional()<\/code> with a default means a caller who wants the simple case writes two lines instead of six. nullable = false<\/code> means a caller cannot pass null<\/code> and get a confusing failure three resources deep. The validation<\/code> block means a typo fails at plan time with a sentence a human wrote, rather than as a provider error about an invalid parameter.<\/p>\n\n\n\n
That last one matters more than it looks. Every validation rule a module author writes is an error message you do not have to debug.<\/p>\n\n\n\n
3. You can pin it, and the pin means something<\/h3>\n\n\n\n
This trips people up because the two common source types behave differently.<\/p>\n\n\n\n
# Registry source. The version argument applies here.\nmodule \"vpc\" {\n  source  = \"terraform-aws-modules\/vpc\/aws\"\n  version = \"~> 5.0\"   # allows any 5.x, refuses 6.0\n}\n\n# Git source. There is no version argument. Pin with ref.\nmodule \"internal_network\" {\n  source = \"git::https:\/\/git.example.com\/infra\/tf-network.git?ref=v2.3.1\"\n}<\/code><\/pre>\n\n\n\n
The ~><\/code> operator only allows the rightmost specified component to increase. Written against a major and minor, as above, it accepts patch and minor releases and blocks the next major. Written as ~> 5.0.1<\/code> it accepts patches only. Which one you want depends entirely on whether you trust the author’s reading of semantic versioning, and the honest answer for third-party modules is usually “not enough to auto-accept minors in production”.<\/p>\n\n\n\n
For Git sources, pin to a tag, not a branch. A branch reference resolves to whatever the tip happens to be at init<\/code> time, which turns your infrastructure into a moving target and makes a plan from two weeks ago unreproducible.<\/p>\n\n\n\n
4. It has tests you can run without a cloud account<\/h3>\n\n\n\n
Terraform’s built-in test framework uses .tftest.hcl<\/code> files and the same HCL you already write. The critical detail for module authors is that a run block set to command = plan<\/code> creates nothing. No credentials, no resources, no teardown, no cost. It just checks that the configuration produces what you claimed.<\/p>\n\n\n\n
# tests\/validation.tftest.hcl\n# Runs on plan only. Nothing is created and nothing is billed.\n\nrun \"rejects_unknown_environment\" {\n  command = plan\n\n  variables {\n    environment = \"produciton\"\n  }\n\n  expect_failures = [var.environment]\n}<\/code><\/pre>\n\n\n\n
Negative tests like that are the cheapest quality signal in the whole ecosystem. They prove the validation rules actually fire, which is the difference between a rule that catches typos and a rule that was written once and silently broken later.<\/p>\n\n\n\n
OpenTofu runs the same format through tofu test<\/code>, and additionally recognises a .tofutest.hcl<\/code> extension for tests that should only run there. Useful if you maintain modules that target both tools.<\/p>\n\n\n\n
5. Somebody answers issues<\/h3>\n\n\n\n
Least technical, most predictive. Open the issue tracker, sort by recently updated, and look at whether maintainers reply. A module with a hundred open issues and active triage is in far better shape than one with six open issues and no comments since a provider major release.<\/p>\n\n\n\n
Provider major versions are the stress test. When the AWS or Azure provider ships a breaking change, every module has to react. Modules without a maintainer simply stop being usable, and you find out when init<\/code> refuses to resolve a version constraint.<\/p>\n\n\n\n
\n\n\n\n
Three kinds of module, and which ones actually pay off<\/h2>\n\n\n\n
Not everything that can<\/em> be a module should<\/em> be. It helps to name the three shapes you see in the wild.<\/p>\n\n\n\n
The thin wrapper<\/h3>\n\n\n\n
One resource, a handful of variables passed straight through, maybe a tag merge. This is the most common module and usually the least valuable. It adds a layer of indirection, a version to track and a state address prefix, in exchange for saving four lines.<\/p>\n\n\n\n
There is one case where it earns its place: when the wrapper is enforcing something, like mandatory encryption, a naming convention, or a tag schema your finance team depends on. Then it is not a wrapper, it is a policy with a friendly interface. If it enforces nothing, inline the resource and move on.<\/p>\n\n\n\n
The composition module<\/h3>\n\n\n\n
Five to fifteen resources that only make sense together. A VPC with its subnets, route tables and gateways. A service with its task definition, target group, listener rule and log group. This is where modules earn back their cost, because the value is in the wiring, and the wiring is exactly what people get wrong when they copy and paste.<\/p>\n\n\n\n
Most modules worth reusing live here.<\/p>\n\n\n\n
The landing zone<\/h3>\n\n\n\n
An entire environment behind one module call. Accounts, networking, IAM baseline, logging, the lot. These are genuinely powerful and genuinely expensive. They only work when a team owns them, tests them, and has a release process. A landing zone module maintained by one person as a side project becomes the single scariest thing in the repository, because nobody can upgrade it and nobody can replace it either.<\/p>\n\n\n\n
Public modules or your own?<\/h2>\n\n\n\n
The case for public modules is stronger than the “we have specific needs” crowd usually admits. The community AWS collections in particular have absorbed years of edge cases you have not thought of yet: the ordering constraints, the optional sub-resources, the arguments that only apply in certain regions. Reimplementing that from the provider docs is a real project, not an afternoon.<\/p>\n\n\n\n
The case against is equally real. Popular public modules are wide by necessity, because they serve everyone. That width shows up as a large input surface, a lot of conditional logic, and majors that shuffle internals. You inherit an upgrade cadence you do not control.<\/p>\n\n\n\n
My rough split: use public modules for undifferentiated infrastructure where the community has clearly solved it, and write your own for anything encoding a decision your organisation made. A VPC is undifferentiated. Your service deployment pattern is not.<\/p>\n\n\n\n
There is a licensing dimension worth knowing about. Terraform moved from an open source licence to the source-available Business Source License, which is what prompted the OpenTofu fork now under the Linux Foundation. Module code itself is unaffected by that change, and the two tools read the same HCL, so modules generally work with either. OpenTofu runs its own registry rather than HashiCorp’s. If your organisation has strict open source licensing requirements, that distinction is the one to escalate, and it is a legal question rather than a technical one.<\/p>\n\n\n\n
For sharing modules internally, a private registry gives you discovery and a version list in one place. HCP Terraform includes one, and the run platforms built around Terraform and OpenTofu, such as Spacelift, Scalr and env0, all offer module catalogs with policy enforcement attached. You can also get most of the benefit from tagged Git repositories on GitHub or GitLab and a README, which is where I would start before paying for anything. If you self-host your Git server and CI runners, they need somewhere to live, and a small VPS from a provider like InterServer, Hetzner or DigitalOcean handles module CI comfortably, since the plans are cheap and the tests never leave the plan phase.<\/p>\n\n\n\n
Making your own modules worth reusing<\/h2>\n\n\n\n
If you are on the authoring side, this is the order I would do things in.<\/p>\n\n\n\n
    \n
  1. Write it inline first, twice.<\/strong> Do not modularise a pattern you have seen once. The second copy tells you which parts vary and which parts are actually fixed. That is the module’s interface, discovered rather than guessed.<\/li>\n\n\n\n
  2. Extract with moved<\/code> blocks in the same commit.<\/strong> Moving a resource into a module changes its address. If the resource holds data, that is the difference between a refactor and an outage.<\/li>\n\n\n\n
  3. Type the inputs properly.<\/strong> Objects with optional()<\/code> defaults over flat strings, nullable = false<\/code> where null makes no sense, validation<\/code> blocks with error messages that name the fix.<\/li>\n\n\n\n
  4. Prefer for_each<\/code> over count<\/code> for anything collection-shaped.<\/strong> With count<\/code>, removing an element from the middle of a list shifts every index after it, and Terraform plans a rebuild of resources you never touched. Keyed addresses do not shift.<\/li>\n\n\n\n
  5. Generate the docs.<\/strong> terraform-docs<\/code> reads your variables and outputs and writes the README table. Wire it into CI so the docs cannot drift from the code, because hand-written input tables are always out of date.<\/li>\n\n\n\n
  6. Lint and scan on every PR.<\/strong> terraform fmt -check<\/code>, terraform validate<\/code>, tflint<\/code> for provider-specific mistakes, and a policy scanner such as Checkov or Trivy for the security defaults. All of these run in seconds on a plain GitHub Actions or GitLab CI runner.<\/li>\n\n\n\n
  7. Tag releases, and mean it.<\/strong> A major for anything that changes an address or removes an input. A minor for new optional inputs. Consumers pin against your tags, so the tag is a promise.<\/li>\n<\/ol>\n\n\n\n
    One thing I would skip early on: building a full integration test suite that applies real infrastructure. It is slow, it costs money, and it needs credentials in CI. Plan-mode tests plus a policy scanner catch most of what actually breaks. Add applied tests later, for the two or three modules where the wiring is genuinely subtle.<\/p>\n\n\n\n
    Troubleshooting the plans that scare you<\/h2>\n\n\n\n
    “Forces replacement” after a version bump<\/h3>\n\n\n\n
    Before you argue with it, find out what it wants to delete. Save the plan and read it as JSON rather than scrolling terminal output.<\/p>\n\n\n\n
    terraform init -upgrade\nterraform plan -out=tfplan\n\n# List every address the plan intends to delete.\nterraform show -json tfplan | jq -r '.resource_changes[]\n  | select(.change.actions[] == \"delete\") | .address'<\/code><\/pre>\n\n\n\n
    If the list is empty, the replacement was an argument change, not an address change, and you should read the diff on that resource. If the list contains things you did not expect, compare the addresses against the new module version’s source. A rename with no moved<\/code> block is the usual answer, and you can write the moved<\/code> block yourself in your root configuration as a workaround.<\/p>\n\n\n\n
    A module with a provider block inside it<\/h3>\n\n\n\n
    Modules should declare which providers they need, not configure them. A module that contains a configured provider<\/code> block rather than just a required_providers<\/code> entry limits what callers can do with it, including using for_each<\/code> or count<\/code> on the module call. It also makes the module harder to destroy cleanly. If you hit that, the fix is on the module side: move provider configuration up to the root and pass configuration aliases in.<\/p>\n\n\n\n
    Changes to the module source are not picked up<\/h3>\n\n\n\n
    Remote modules are downloaded into the working directory during init<\/code>. Changing a ref<\/code> or a version<\/code> constraint in your configuration does not re-download anything on its own. Run terraform init -upgrade<\/code>. If your CI caches the module directory between runs, that cache is the first place to look when a pipeline plans against code you are sure you deleted.<\/p>\n\n\n\n
    Registry version list looks stale<\/h3>\n\n\n\n
    A registry’s list of versions is a synced view of your Git tags, not an independent database. Reconnecting a VCS integration, moving repositories, or pushing many tags at once can leave the registry out of step with the repository. Treat the tags as the source of truth and check the registry’s view after any change to that integration.<\/p>\n\n\n\n
    Common mistakes<\/h2>\n\n\n\n