Terraform Module Design Best Practices: Reusability and Maintainability

Modules need to deliver reusability while drawing boundaries that hold up under change. This article focuses on stable design guidelines aligned with the official docs, organized so they double as exam prep.

In particular, minimizing inputs and outputs, handling providers correctly, pinning versions with SemVer, and choosing between count and for_each have the biggest impact on reproducibility and maintainability.

1. Design Principles: Single Responsibility and Clear Boundaries

Keep each module focused on a single responsibility and keep its inputs (variables) and outputs minimal. A small API surface with few side effects makes it easier to swap implementations and to absorb future change.

As a rule, configure providers in the root module and only declare required_providers in child modules. This preserves consumers' freedom to choose authentication, region, and so on.

Make external coupling explicit. Keep things like external resource IDs and tagging strategy at the input boundary, and avoid resolving names inside the module (i.e. don't overuse data sources).

• Restrict inputs/outputs to the minimum needed (avoid breaking changes)
• Configure providers in the root; assume inheritance in children (pass aliases explicitly when needed)
• Hide internal implementation: abstract resource names and structure behind outputs
• Exam angle: memorize the roles of root vs. child modules and the default behavior of provider inheritance

Module boundaries and provider inheritance, at a glance

Skeleton of a minimal module

# modules/network/
# main.tf
resource "aws_vpc" "this" {
  cidr_block = var.cidr_block
}

# variables.tf
variable "cidr_block" {
  type = string
}

# outputs.tf
output "vpc_id" {
  value = aws_vpc.this.id
}

# Usage from the root module (providers are configured in the root)
module "network" {
  source     = "./modules/network"
  cidr_block = "10.0.0.0/16"
}

2. Input Variable Design: Types, Safety, and Validation

Give inputs strict types and allow only meaningful defaults. Vague any types reduce reusability and increase the risk of future breaking changes.

Use validation to catch business-rule violations early, and sensitive = true to keep secrets from leaking. Receive shared things like tags as map(string) and normalize them in locals.

Because list order tends to drift, prefer designs that use map/set with stable keys for data that drives instance branching.

• Use concrete types (string, number, bool, list(string), map(string), object({...}), etc.)
• Check format and range early using validation
• Mark secrets as sensitive and never emit them in plaintext
• Prefer map-based designs intended for for_each to avoid order dependence

Concrete variables.tf examples (types and validation)

variable "name" {
  type = string
  validation {
    condition     = length(var.name) > 0 && length(var.name) <= 63
    error_message = "name must be between 1 and 63 characters."
  }
}

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

variable "ports" {
  type = set(number)
  validation {
    condition     = alltrue([for p in var.ports : p > 0 && p < 65536])
    error_message = "ports must be between 1 and 65535."
  }
}

variable "db_password" {
  type      = string
  sensitive = true
  description = "Database password (injected securely from outside)"
}

3. Outputs and Dependencies: Minimizing Coupling

Limit outputs to the identifiers and connection info consumers actually need; don't leak internal resource structure. Prefer stable values like ARNs and IDs so your module survives future implementation changes.

Mark sensitive outputs to protect confidential data, and use depends_on between modules only when you need explicit ordering. When references exist, the implicit dependency they create takes precedence; depends_on is a last resort.

On the exam, you need to clearly articulate the role of outputs and the meaning of depends_on on a module call.

• Keep outputs minimal (IDs, ARNs, endpoints, etc.)
• Use sensitive = true for confidential values
• Only use depends_on on module calls when there is no implicit dependency

Examples of outputs and module-level depends_on

# modules/network/outputs.tf
output "vpc_id" {
  value = aws_vpc.this.id
}

output "private_subnet_ids" {
  value = aws_subnet.private[*].id
}

# In the root module: when you genuinely need explicit ordering
module "network" {
  source     = "./modules/network"
  cidr_block = "10.0.0.0/16"
}

module "app" {
  source = "./modules/app"
  vpc_id = module.network.vpc_id
  # The vpc_id reference usually makes the implicit dependency enough
}

# The rare case where there is no reference but you still need ordering
module "audit" {
  source = "./modules/audit"
  depends_on = [module.network]
}

4. Providers and Versioning: Ensuring Predictability

Set required_version in the terraform block to force the whole team onto the same Terraform version range. In required_providers, spell out each provider's source and version constraint.

Child modules should not configure providers; they should only declare requirements via required_providers, letting the root module control behavior via inheritance or explicit aliases.

Version the module itself with VCS tags and follow SemVer: breaking changes bump the major version, backward-compatible features bump the minor, and bug fixes bump the patch.

• Pin a minimum CLI version with required_version
• Pin each provider's source and version range in required_providers
• Release modules with VCS tags following SemVer
• Exam angle: be able to explain the ~> operator and the defaults of provider inheritance

terraform, provider, and how to pass providers to a module

# Root module
terraform {
  required_version = ">= 1.3.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # pin to 5.x (excludes a future 6.x)
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "us_west_2"
  region = "us-west-2"
}

module "compute" {
  source    = "./modules/compute"
  providers = {
    aws = aws.us_west_2
  }
}

# Child module (modules/compute)
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0"
    }
  }
}
# As a rule, do not define a provider "aws" block here (inherit it from the root)

5. Structure, Documentation, and Quality Checks

Split directories under modules/ by capability, and put minimal usage examples in examples/. The README should clearly list inputs, outputs, dependencies, and supported version ranges.

In CI, use terraform fmt -recursive and terraform validate to enforce style and syntax consistency, and watch plan diffs. Publish modules via tags and call out breaking changes in the CHANGELOG.

Examples are the fastest path to real-world testing. Keep examples/ as a minimal config that actually runs plan/apply, and make sure readers can override the provider setup.

• Maintain modules/, examples/, and a README (inputs/outputs/compatibility) as a set
• Basic CI trio: fmt, validate, plan
• Use version tags and a changelog to keep downstream users safe

Recommended layout and quality checks

# Example repository layout
.
├── modules/
│   ├── network/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── compute/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
├── examples/
│   └── simple/
│       ├── main.tf
│       └── providers.tf
└── README.md

# CI basics (shell)
terraform fmt -recursive
terraform validate
terraform -chdir=examples/simple init
terraform -chdir=examples/simple plan

6. Patterns and Anti-Patterns That Drive Reusability

When you're adding/removing instances or key stability matters, prefer for_each over count to avoid index drift. Repeated nested blocks should be generated via dynamic blocks.

Over-relying on data sources for external lookups increases apply-order and environment dependencies, which hurts maintainability. As a rule, take required IDs and config via inputs and normalize them in locals.

Common anti-patterns: accepting any for everything, leaking internal implementation through outputs, and locking in providers by configuring them in child modules. They strip downstream consumers of flexibility and invite breaking changes.

• Add/remove resources → for_each; repeated nested blocks → dynamic; simple fixed counts → count is fine
• Minimize external lookups; lock the boundary at inputs and normalize in locals
• Avoid configuring providers in child modules (use required_providers only)

Address stability: for_each vs. count

# count (fragile when the order shifts)
variable "names" { type = list(string) }
resource "aws_iam_user" "u" {
  count = length(var.names)
  name  = var.names[count.index]
}
# Reordering names can force many replacements

# for_each (robust as long as the keys are stable)
variable "users" { type = set(string) }
resource "aws_iam_user" "u2" {
  for_each = var.users
  name     = each.value
}
# As long as each key (the user name) stays the same, the diff stays minimal

Check Your Understanding

Frequently Asked Questions