Terraform Modules vs. Resources: When to Promote a Pattern

Terraform gives you two ways to express the same infrastructure. You can declare resources directly, or you can wrap them in a module and call that module with inputs. Both produce identical cloud objects. The choice is not about capability, it is about where you want the complexity to live and who you want to be responsible for it.

Most teams get this decision wrong in one of two directions. Some modularize on day one and end up with a registry full of thin wrappers that add a layer of indirection and little else. Others never modularize at all, and end up with the same forty lines of bucket configuration copy-pasted across nine environments, each quietly diverging from the others in ways nobody has time to reconcile.

This guide covers the distinction that actually matters in practice, the signals that tell you a pattern is ready to be promoted into a module, and the mechanics of promoting it without Terraform tearing down your infrastructure on the way. For module anatomy, input and output design, and composition patterns, see our Terraform modules guide, which this article treats as background rather than repeating.

Disclaimer

Everything discussed here works the same way in OpenTofu, the open-source Terraform alternative. To keep things familiar for DevOps engineers, we use Terraform terminology as a catch-all throughout.

The distinction that actually matters

The textbook answer is that a resource represents one object managed by a provider, while a module is a container for multiple resources that can be reused. That is correct, and it is also not the part that will cost you a weekend.

A resource is a unit of change

A resource block maps to a single provider-managed object and carries a single address in state. When you declare an S3 bucket at the root of your configuration, Terraform tracks it as [.code]aws_s3_bucket.logs[.code]. Every plan compares that address against the real world and proposes the smallest reconciliation it can.

resource "aws_s3_bucket" "logs" {
  bucket = "acme-prod-access-logs"
}

resource "aws_s3_bucket_versioning" "logs" {
  bucket = aws_s3_bucket.logs.id

  versioning_configuration {
    status = "Enabled"
  }
}

# State address: aws_s3_bucket.logs

Resources are maximally explicit. Everything the provider supports is available to you at the call site, the plan output names attributes you recognize, and debugging means reading one file.

A module is a unit of interface

A module is a boundary. It takes inputs, produces outputs, and hides whatever happens in between. The moment you wrap that same bucket in a module, its state address changes to [.code]module.logging.aws_s3_bucket.this[.code]. The cloud object is unchanged. The identity Terraform uses to track it is not.

module "logging" {
  source = "./modules/log-bucket"

  name       = "acme-prod-access-logs"
  versioning = true
}

# State address: module.logging.aws_s3_bucket.this

That address change is the single most important mechanical fact in this article. It is why moving resources into modules is dangerous by default, and it is covered in detail further down.

The tradeoff, stated honestly

A resource gives you control and visibility. A module gives you a contract. A contract is worth having when several callers need the same guarantees, and it is pure overhead when there is only one caller and the guarantees are still being invented.

• Resources optimize for clarity now. You can see everything, change anything, and nothing breaks for anyone else.
• Modules optimize for consistency later. You change one interface and every consumer inherits the change, which is exactly as powerful and as dangerous as it sounds.

Start with resources, then promote deliberately

The default that holds up across most teams is to write resources first and promote to a module once the pattern has proven itself. Both halves of that sentence carry weight, because promoting at the wrong time is expensive in both directions.

What promoting too early costs

The most common failure is the wrapper module: a module that contains one resource and exists mainly because someone decided modules were good practice. It passes a dozen variables straight through to the provider and adds nothing but a layer.

# modules/bucket/main.tf
# An anti-pattern: this module makes no decisions of its own.

variable "bucket" {
  type = string
}

variable "tags" {
  type    = map(string)
  default = {}
}

resource "aws_s3_bucket" "this" {
  bucket = var.bucket
  tags   = var.tags
}

output "id" {
  value = aws_s3_bucket.this.id
}

output "arn" {
  value = aws_s3_bucket.this.arn
}

# The caller gains nothing and loses direct access to every
# other argument the aws_s3_bucket resource supports.

This pattern taxes you every time you touch it:

1. Every new provider argument a caller needs becomes a change to the module, a version bump, and an upgrade for every consumer. The provider already supported it. Your abstraction did not.
2. The module's [.code]variables.tf[.code] slowly becomes a worse-documented, always-stale copy of the provider schema.
3. Debugging requires reading two files instead of one, and the plan output now references addresses that do not match the code a newcomer is looking at.
4. You have created a versioning obligation and an owner without buying any consistency, because there is only one caller.

A module earns its indirection by encoding decisions, not by forwarding arguments. If you cannot name a decision the module makes on the caller's behalf, such as a naming convention, an encryption default, a required tag set, or a hardened policy attachment, it is not ready to be a module.

What promoting too late costs

The opposite failure is quieter and more expensive. Copy-pasted resource blocks do not stay identical. One environment gets versioning enabled during an audit, another gets a lifecycle rule during a cost review, a third gets neither because the person doing the work was on call that week.

Six months later nobody can answer which copy is correct, and a single security change has to be applied by hand in nine places, each of which needs its own review and its own plan. This is also the point at which a well-intentioned bulk find-and-replace becomes the most dangerous change in the repository.

Five signals a pattern is ready to become a module

Rather than a feeling, use signals you can point at in a pull request.

1. You are writing the third copy

The rule of three travels well from software engineering. The first instance teaches you the requirement. The second reveals which parts vary. The third is where copy-paste stops being pragmatic and starts being debt, because you now have enough information to know what the interface should be.

2. The input surface has stopped moving

If the set of things that vary between instances changed in the last two weeks, the abstraction is not ready. Modules are expensive to reshape once consumers depend on them, since every interface change becomes a coordinated upgrade. Wait for the variables to settle before you freeze them into a contract.

3. The same review comments keep recurring

When reviewers repeatedly ask about the same naming, tagging, or encryption decisions, those decisions belong in code rather than in review. That is precisely the work a module does well: it makes the correct choice the default and the incorrect choice something you have to opt into visibly.

4. A control has to apply to every instance

Compliance and security requirements are inherently cross-instance. If every bucket in the estate must have encryption, access logging, and public access blocked, a module lets you implement that once and roll it out through a version bump rather than a nine-branch campaign. Note the caveat in the governance section below: a module makes the control available, not mandatory.

5. Consumers will outnumber authors

Modules pay off when the people calling them are not the people maintaining them. If an application team needs to provision a queue without learning your provider's argument surface, the module is the product. If you are the only caller and the only author, you are talking to yourself through an interface.

Signals to wait

• The requirement is still being discovered, and the shape of the configuration changed this week.
• There is one caller and no credible second one on the roadmap.
• The variation between instances is larger than the shared part, which usually means you have found two patterns rather than one.
• Covering the variation would take a dozen or more inputs. A module with a very wide input surface is usually an abstraction drawn in the wrong place.

How to promote resources into a module without destroying them

Here is the part that catches people. When you move a resource into a module, its state address changes. Terraform's default reading of a changed address is that the old object should be destroyed and a new one created. For a stateless resource that is an inconvenience. For a database, an object store, or anything holding data, it is an incident.

A plan against a naive refactor will tell you exactly this, and it is worth learning to recognize the shape of it before you see it under pressure:

$ terraform plan
Plan: 1 to add, 0 to change, 1 to destroy.

One to add and one to destroy, for a refactor where you changed no arguments, means Terraform has lost track of the object's identity. Do not apply that plan.

Declare the move with a moved block

Since Terraform v1.1, the [.code]moved[.code] block lets you record the address change in configuration so Terraform treats it as a rename rather than a replacement. HashiCorp documents this as the supported way to refactor module addresses, and it is plannable, which means you can see the outcome before committing to it.

# The resource blocks have moved into ./modules/log-bucket.
# Declare the address change so Terraform renames instead of replaces.

moved {
  from = aws_s3_bucket.logs
  to   = module.logging.aws_s3_bucket.this
}

moved {
  from = aws_s3_bucket_versioning.logs
  to   = module.logging.aws_s3_bucket_versioning.this
}

Before planning the new address, Terraform checks state for an existing object at the [.code]from[.code] address, renames it to the [.code]to[.code] address, and then plans as if the object had always lived there. The correct plan for a pure promotion is unambiguous:

$ terraform plan
Plan: 0 to add, 0 to change, 0 to destroy.

Zero on all three counts is the gate. If you see anything else after adding your moved blocks, an address is wrong, and the fix is in the block rather than in the state.

Moving many resources and changing keys at the same time

Promotion rarely involves one resource. You will usually be moving a handful of related resources into a module at once, and often switching from individual instances to [.code]count[.code] or [.code]for_each[.code] in the same change. The [.code]moved[.code] block handles both: when either address includes an instance key, Terraform treats the addresses as referring to specific instances, so you can move between keyed and unkeyed forms in the same refactor.

# Promoting three hand-written environments into one for_each module call.

moved {
  from = aws_s3_bucket.logs_dev
  to   = module.logging["dev"].aws_s3_bucket.this
}

moved {
  from = aws_s3_bucket.logs_staging
  to   = module.logging["staging"].aws_s3_bucket.this
}

moved {
  from = aws_s3_bucket.logs_prod
  to   = module.logging["prod"].aws_s3_bucket.this
}

# Adopting for_each on an existing count-based resource works the
# same way: count index to map key.
moved {
  from = aws_subnet.private[0]
  to   = aws_subnet.private["eu-west-1a"]
}

If you are new to iterating over collections, our guide to terraform for_each covers the collection types and gotchas in depth.

When the move crosses a state boundary

Moved blocks work within a single state file. If your promotion also splits configuration across state files, such as pulling a shared networking layer out into its own workspace, you need a different tool. HashiCorp recommends removing the resource from the source state and importing it into the target state, using the configuration-driven [.code]removed[.code] block, added in Terraform v1.7, together with the [.code]import[.code] block from v1.5. Both are plannable and both leave a record in configuration history, which [.code]terraform state mv[.code] does not.

# In the SOURCE configuration: forget the object, do not delete it.
removed {
  from = aws_vpc.shared

  lifecycle {
    destroy = false
  }
}

# In the TARGET configuration: adopt the existing object.
import {
  to = module.network.aws_vpc.this
  id = "vpc-0a1b2c3d4e5f"
}

# Omitting the lifecycle block destroys the real resource.
# Plan first, and read the plan.

The [.code]lifecycle[.code] block is doing the load-bearing work in the [.code]removed[.code] example. Setting destroy to false is what tells Terraform to forget the object rather than delete it. Getting that wrong deletes production. Our guide to the import command and import block covers the import side in detail, and the Terraform state file guide covers the underlying state operations.

How long to keep the moved blocks

For a configuration you alone own, you can remove moved blocks once the change is applied everywhere. For a shared module, keep them. HashiCorp's guidance is that removing them is only safe when you are certain every consumer has run an apply against the new version, and in a large organization that certainty is difficult to obtain and easy to assume incorrectly. The blocks are cheap to keep and they double as a changelog of the module's structural history.

Operating the module once it exists

Promotion is the beginning of the obligation, not the end of it. A module with consumers is a product with users.

Iterate over the module, not the copies

The payoff for the interface is that scale becomes a data problem rather than a code problem. Since Terraform 0.13, [.code]for_each[.code] and [.code]count[.code] work on module blocks, so twelve near-identical environments become one module call driven by a map.

locals {
  log_buckets = {
    dev     = { versioning = false, retention_days = 7 }
    staging = { versioning = false, retention_days = 30 }
    prod    = { versioning = true, retention_days = 365 }
  }
}

module "logging" {
  source   = "./modules/log-bucket"
  for_each = local.log_buckets

  name           = "acme-${each.key}-access-logs"
  versioning     = each.value.versioning
  retention_days = each.value.retention_days
}

Version the interface

An unversioned module is a shared mutable variable across every environment you own. Pin module sources to a version constraint so a change to the module does not retroactively change infrastructure that nobody deployed. Registry-sourced modules support the [.code]version[.code] argument, and our Terraform Registry guide covers publishing, semantic versioning, and constraint syntax.

module "logging" {
  # Registry source with a pinned version constraint.
  source  = "app.env0.com/acme/log-bucket/aws"
  version = "~> 2.4"

  name       = "acme-prod-access-logs"
  versioning = true
}

# "~> 2.4" accepts 2.4.x and 2.5.x but never 3.0.0, so a breaking
# interface change cannot arrive unannounced.

Test module changes before consumers inherit them

Once a module has consumers, an untested change is a change to every one of them at once. Terraform's native test framework, generally available since v1.6, lets you write tests in HCL in [.code].tftest.hcl[.code] files, with each [.code]run[.code] block executing a plan or apply and asserting against the result. Terraform v1.7 added provider mocking, which makes it practical to unit-test a module without creating real infrastructure or holding cloud credentials.

# tests/defaults.tftest.hcl

mock_provider "aws" {}

variables {
  name = "test-bucket"
}

run "versioning_defaults_off" {
  command = plan

  assert {
    condition     = aws_s3_bucket_versioning.this.versioning_configuration[0].status == "Suspended"
    error_message = "Versioning must default to off for non-production callers."
  }
}

run "encryption_is_not_optional" {
  command = plan

  assert {
    condition     = aws_s3_bucket_server_side_encryption_configuration.this != null
    error_message = "Module must always attach server-side encryption."
  }
}

$ terraform test
tests/defaults.tftest.hcl... pass
Success! 4 passed, 0 failed.

For how the native framework compares to the Go-based alternative, see our Terratest vs. Terraform/OpenTofu test comparison.

Where modules stop being governance

Module discussions often end with the claim that modules give you governance, because standards are encoded once and reused everywhere. That is half true, and the missing half matters more than the present one.

A module is a convention. It is opt-in. Nothing in Terraform prevents an engineer from skipping your hardened bucket module and writing a raw resource block with public access enabled, and nothing in Terraform prevents that configuration from applying cleanly. Your module encoded the standard. It did not enforce it.

Enforcement requires something that evaluates the plan regardless of how the configuration was written. That is the job of policy-as-code:

• A module makes the compliant path the easy one.
• A policy makes the non-compliant path impossible, or at least impossible without a recorded human approval.

Those are complementary layers, not substitutes, and teams that ship only the first one tend to discover the gap during an audit. Our guides to using Open Policy Agent with Terraform and how policy-as-code enhances infrastructure governance cover the enforcement layer.

There is a third gap that neither modules nor policies close on their own: resources that exist in your cloud accounts but appear in no configuration at all. A module cannot standardize something it has never seen, and a plan-time policy never evaluates a resource created by hand in a console. Closing that loop requires comparing what is actually deployed against what your IaC claims to manage.

Managing the resource-to-module lifecycle with env zero

The decisions above are Terraform decisions and they hold regardless of what you run Terraform on. The operational half, distributing modules, gating changes, and knowing what is outside the model, is a platform problem.

Distribute modules through a private registry

env zero includes a private module registry so internal modules get the same versioning, discovery, and documentation surface as public ones without leaving your organization. Module versions map to Git tags following semantic versioning, the readme renders from the repository, and each module page includes a prefilled source snippet for callers. Multiple modules can live in one repository using folder-based module paths.

Gate module changes with continuous testing

The registry can run your tests for you. With module continuous integration testing enabled, env zero executes the tftest files in your module directory on every commit to the default branch, and optionally on every pull request targeting it. Infrastructure is created, tested, and destroyed in a single flow, results and run history are retained, and status checks surface in your VCS so a failing module change is visible in review rather than after release.

Enforce the standard the module encodes

Because a module cannot compel its own use, env zero evaluates the plan itself. Policies let you apply OPA rules to deployments regardless of how the configuration was authored, and approval policies require a recorded human decision on changes that cross a threshold you define. This is the layer that turns a convention into a control.

Give consumers a path that does not require authoring HCL

Templates expose a curated module as a self-service option, so an application team provisions from an approved pattern with the variables you decided to expose. That is the point at which the module stops being an internal convenience and becomes the interface between the platform team and everyone else.

Find the resources no module ever touched

Cloud Compass audits IaC coverage across your cloud accounts and surfaces resources that exist but are unmanaged, which is the population your modules and your policies are both blind to. Codifying those into configuration is what makes the standard you encoded actually universal rather than merely available.

Final thoughts

Resources and modules are not competing approaches to be chosen once. They are two points in a lifecycle. New and uncertain work belongs in resources, where it is explicit and cheap to change. Proven and repeated work belongs in modules, where it is consistent and cheap to roll out. The skill is recognizing the transition and executing it without collateral damage.

Concretely: write resources until the third copy, promote when the input surface stops moving, use [.code]moved[.code] blocks and insist on a plan showing zero destroys, version the interface, test before consumers inherit changes, and remember that the module is the convention while policy is the control.

For structuring the repositories all of this lives in, see our Terraform repository strategies and structures guide, and for module ownership across multiple teams, our guide to scaling ownership and platform layer design.

Frequently asked questions

Q. What is the difference between a Terraform module and a resource?

A resource is a single object managed by a provider and the smallest unit of change Terraform tracks. A module is a container that groups configuration behind an interface of inputs and outputs so it can be reused. The practical difference is state identity: the same bucket declared at the root has the address aws_s3_bucket.logs, and inside a module it becomes module.logging.aws_s3_bucket.this.

Q. Should I create a Terraform module for a single resource?

Usually not. A module wrapping one resource and forwarding arguments to the provider adds indirection, a versioning obligation, and an upgrade path for consumers without buying consistency. A module earns its place by encoding decisions such as naming conventions, encryption defaults, or required tags, not by passing variables through.

Q. How do I move resources into a Terraform module without destroying them?

Use a moved block, available since Terraform v1.1, to declare the old and new addresses so Terraform treats the change as a rename rather than a replacement. Then run a plan and confirm it reports zero to add, zero to change, and zero to destroy before applying. If the move also crosses into a different state file, use removed and import blocks instead.

Q. Can I use for_each on a Terraform module block?

Yes. Since Terraform 0.13, both for_each and count work on module blocks, which is how you turn many near-identical environments into a single module call driven by a map. Moved blocks also support switching between keyed and unkeyed addresses, so you can adopt for_each during a refactor without recreating resources.

Q. Do Terraform modules enforce infrastructure standards?

No. Modules make a standard available and convenient, but using them is optional and nothing stops an engineer from writing a raw resource block that bypasses the module entirely. Enforcement requires policy-as-code that evaluates the plan regardless of how the configuration was written, with approval gates on sensitive changes.

Related: our Terraform modules guide covers module anatomy and composition, and env0’s Terraform integration brings module distribution, policy enforcement, and deployment guardrails to the workflow.