A Terraform module review should verify more than whether terraform plan completes successfully. Use this reusable checklist to assess secure inputs, stable interfaces, provider constraints, state behavior, dependency design, testing, documentation, and the risk of changing infrastructure that other teams already rely on.
Overview
A reusable Terraform module is an interface around infrastructure. Its variables are inputs, its resources are implementation details, and its outputs are the values that callers are expected to consume. A good review therefore asks two questions at the same time:
- Will this module create and manage the intended infrastructure safely?
- Will existing callers continue to understand and use the module after the change?
The second question is easy to overlook. A module can be technically valid while still creating avoidable operational risk through a changed resource address, a broader IAM policy, an unstable output, an accidental replacement, or an undocumented assumption about networking and providers.
Review the module in layers. Start with its public contract, then inspect security-sensitive inputs and resources, followed by provider and state behavior. Finish with tests, examples, documentation, and a plan produced against a realistic configuration. This separates interface problems from implementation problems and makes the review easier to repeat in pull requests.
Reusable module or environment configuration?
| Use a reusable module when... | Prefer environment-specific configuration when... |
|---|---|
| The same infrastructure pattern appears across teams or environments. | The code represents a one-off composition or temporary migration. |
| Inputs and outputs can be defined with a stable, understandable contract. | The configuration depends heavily on one environment's naming, network, or lifecycle. |
| Defaults and validation can prevent common misuse. | Adding abstraction would hide important decisions from the operator. |
| Consumers benefit from a consistent upgrade path. | The resources are tightly coupled to a single application's release process. |
Abstraction is useful when it reduces repeated decisions without concealing decisions that must remain visible. If a module requires many exceptions, conditional branches, or environment-specific overrides, review whether it should be split or kept as local configuration.
Checklist by scenario
Before publishing a new module
- Define the contract: document what the module creates, what it does not create, required inputs, optional inputs, outputs, and assumptions about accounts, regions, networks, or naming.
- Review variable types: use precise types rather than broad values where practical. A structured object can make required settings clearer than a loosely typed map.
- Validate inputs: reject unsupported values, empty identifiers, invalid patterns, unsafe ranges, and incompatible combinations before resources are applied. Validation should explain how to correct the input.
- Mark sensitive values: identify passwords, tokens, private keys, and other confidential inputs as sensitive where appropriate. Also check whether those values could still appear in state, logs, plans, outputs, or external systems.
- Constrain providers: declare the provider source and a deliberate version constraint. Keep the required Terraform or OpenTofu language version aligned with the syntax and features used by the module.
- Check resource naming: use predictable names and stable resource addresses. Avoid names that depend on incidental ordering when a map or a stable key would provide clearer identity.
- Inspect lifecycle behavior: understand whether changes update, replace, or retain resources. Treat lifecycle settings such as replacement ordering, ignored changes, and deletion protection as explicit operational decisions.
- Limit permissions: review every IAM role, policy, security group rule, and service account permission. The module should request only the access needed for its stated purpose.
- Provide a working example: include a minimal example that can be read and tested independently. Show realistic inputs without committing secrets or environment-specific identifiers.
- Document outputs: explain what each output represents, whether it is stable, and whether consumers should use it for configuration, monitoring, or subsequent module composition.
Before updating a module already in use
- Compare the current and proposed resource addresses. A rename or change from
counttofor_eachcan look small in code while changing how Terraform identifies existing objects. - Generate a plan using a representative consumer configuration, not only the module's example. Review additions, updates, replacements, and destructions individually.
- Check whether provider upgrades alter defaults, validation, import behavior, or resource replacement decisions.
- Identify variables, outputs, and resource names that consumers may reference directly. Decide whether the change is backward compatible, requires a migration, or deserves a major module version.
- Review state operations separately from resource changes. If addresses must move, make the required state migration explicit and test it in a safe environment before applying it to shared state.
- Update examples and upgrade notes at the same time as the implementation. A module is not ready when only its source code has changed.
Before a production apply
- Confirm the selected workspace, account, subscription, project, region, and backend are the intended targets.
- Verify that the plan was generated from the reviewed commit and the expected variable values.
- Check for unexpected replacements, permission expansion, public exposure, network rule changes, and deletion of retained data.
- Confirm that sensitive values are supplied through the approved secret mechanism rather than shell history, committed variable files, or unprotected logs.
- Ensure an operator knows how to pause, recover, or roll back the change. Infrastructure rollback is not always a simple reversal, particularly when data or provider-side defaults are involved.
What to double-check
Some review areas deserve a deliberate second pass because they combine code behavior with operational consequences.
Inputs, defaults, and secrets
Defaults should represent safe, broadly applicable behavior rather than silently choosing an expensive, public, or difficult-to-reverse option. Avoid default values that imply a production decision, such as a broad CIDR range or an unrestricted administrative role. For required settings, making the caller provide an explicit value is often clearer than hiding the decision in a default.
Marking a variable as sensitive improves display behavior, but it does not automatically remove the value from state or from a downstream service. Review the complete data path: input, resource argument, state, output, plan, logs, and provider API. Treat state storage and access controls as part of the module's security design.
Provider constraints and dependency design
Provider constraints should prevent untested versions while leaving a maintainable upgrade path. Constraints that are too broad can allow an unreviewed behavior change; constraints that are too narrow can make routine upgrades unnecessarily difficult. Record provider aliases and required configurations clearly when a module can operate across regions or accounts.
Prefer explicit dependencies when the relationship cannot be inferred from a referenced attribute. At the same time, avoid adding broad depends_on declarations that serialize unrelated resources or cause plans to become less precise. A dependency should explain a real ordering requirement, not compensate for unclear data flow.
State, identity, and drift
Ask how Terraform identifies every managed object and what happens when a key changes. Stable keys are especially important for collections. Review imports, moved resources, retention settings, and any resource that may be changed outside Terraform. If a team intentionally permits external changes, document how drift is detected and reconciled instead of hiding it with a wide ignore rule.
For broader infrastructure reviews, pair this checklist with a release-specific review of deployment manifests. The Helm chart review checklist covers related concerns around values, dependencies, and safe releases, while the Kubernetes resource requests and limits guide can help verify workload sizing when the module provisions Kubernetes infrastructure.
Testing and review evidence
Use more than a syntax check. A practical module test sequence can include formatting, validation, static analysis, provider initialization, plan tests with valid inputs, plan tests with invalid inputs, and an apply-and-destroy test where the environment permits it. Test the important branches: optional resources, alternate regions, disabled features, empty collections, and upgrades from a prior fixture.
Keep the reviewed plan, test output, and migration notes associated with the change. Evidence does not need to be elaborate, but another engineer should be able to see which assumptions were checked.
Common mistakes
- Testing only the happy path: valid defaults do not prove that invalid or incomplete inputs fail safely. Add negative cases for values that operators are likely to enter incorrectly.
- Using a module for every resource: abstraction can make simple configuration harder to understand. Keep local composition visible when the pattern is not repeated or the interface would be artificial.
- Changing names casually: changing a Terraform label, collection key, or module path can change state identity. Treat naming changes as migrations, not cosmetic refactors.
- Relying on sensitive flags alone: sensitive marking does not replace secure state storage, careful outputs, or log review.
- Overusing ignore rules: ignoring changes may suppress useful drift signals and leave the actual ownership model unclear.
- Accepting broad permissions for convenience: temporary administrative access often becomes a permanent module default. Start with the narrowest practical policy and document exceptional access.
- Reviewing code without reviewing the plan: the plan is where provider behavior, computed values, replacements, and environment-specific effects become visible.
- Leaving examples stale: an outdated example is an executable form of documentation debt. Validate examples as part of the module's CI workflow.
For adjacent delivery workflows, the CI/CD pipeline failure triage playbook provides a useful companion when module checks fail in runners, and the platform maintenance playbook can help connect module ownership to the wider platform runbook.
When to revisit
Keep this checklist available for every module pull request, but schedule deeper reviews when the conditions around the module change. Revisit it before seasonal planning cycles, new environment rollouts, provider upgrades, major Terraform or OpenTofu upgrades, security reviews, and refactors that affect resource addresses or state. It is also worth reviewing after an incident, unexpected drift, a failed rollback, or repeated operator confusion about inputs.
At a minimum, compare the module's declared contract with how consumers actually use it. Remove obsolete variables, clarify assumptions, tighten permissive validation, and confirm that examples still represent the supported path. If the module has accumulated many flags or conditional branches, consider whether its interface should be split into smaller modules or moved back into environment-specific configuration.
Before approving the next change, copy this short review into the pull request:
- Inputs are typed, validated, and appropriately marked sensitive.
- Provider and language constraints are intentional and tested.
- Resource identity, lifecycle, state moves, and replacement risks are understood.
- IAM, network exposure, data retention, and drift behavior were reviewed.
- Representative plans, negative tests, examples, and documentation are current.
- Backward compatibility and any required migration steps are explicit.
- The production plan targets the intended environment and has an owner for the apply and recovery process.
A consistent review does not eliminate infrastructure risk, but it makes assumptions visible before they become state changes. That is the central purpose of a reusable Terraform module: not merely to reduce duplicated code, but to make safe infrastructure decisions repeatable.