Reference · Terraform

Module Design

Modules as functions: the standard structure, the API contract, and refactoring without destroying anything.

The mental model

A module is a directory of .tf files — nothing more. You are always inside one: the directory you run Terraform in is the root module. Calling a module is like calling a function: variables are the parameters, outputs are the return values, and the resources inside are implementation details. The call site gives it a name, and that name becomes a state address namespace: module.vpc.aws_subnet.private[0].

Standard module structure

my-module/
├── main.tf         # resources — the implementation
├── variables.tf    # the API in (every variable: description)
├── outputs.tf      # the API out (every output: description)
├── README.md       # purpose + usage; marks a module as "public" to humans
├── LICENSE
├── examples/       # runnable usage examples
└── modules/        # nested modules (with README = external-use; without = internal)
    └── …

Only the root module is required — the rest is convention that tooling (docs generators, registries) understands.
Prefer many small composable modules over deep nesting — callers should pick and choose.
Reference nested modules by relative path (./modules/cluster).

Source: Standard Module Structure

Calling a module

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"  # registry source
  version = "~> 5.8"                          # ALWAYS pin — registry sources only
  cidr    = var.vpc_cidr                       # variables = arguments
}

# git source pins with ?ref= (tag/commit) instead of version:
# source = "git::https://github.com/acme/tf-vpc.git?ref=v2.3.0"

resource "aws_instance" "app" {
  subnet_id = module.vpc.private_subnet_ids[0]  # outputs = return values
}

An output is only reachable if the module declares it — internals are private by default.
Modules support count/for_each/depends_on (TF ≥0.13).

The provider rule

Reusable modules declare what they need (required_providers) but never contain provider blocks. Provider configuration belongs to the root module; it flows into modules automatically (or explicitly via providers = {…} for multi-region). A legacy provider block inside a module blocks count/for_each on the module call and orphans resources when the module is removed.

Refactoring: the `moved` block

State maps addresses → real objects. Renaming a resource or pulling it into a module changes its address — and Terraform reads that as "destroy the old, create the new."

moved {
  from = aws_s3_bucket.logs
  to   = module.storage.aws_s3_bucket.logs
}

Use for: renaming resources, renaming module calls, moving resources into/out of modules, adding count/for_each to existing resources.
Declarative, reviewable, and survives in version control — prefer it over imperative terraform state mv for shared codebases.
Plan shows the move ("has moved to") with zero infrastructure changes.

Source: Refactoring (moved blocks)

When NOT to write a module

Thin wrappers: a module wrapping a single resource, re-exposing its arguments 1:1, adds indirection with no abstraction — use the resource directly.
A good module raises the abstraction level: it answers "give me a hardened VPC," not "here is aws_vpc with extra steps."
Rule of thumb: if you can't name the concept the module represents, it isn't one yet.

The mental model

Standard module structure

Calling a module

The provider rule

Refactoring: the moved block

When NOT to write a module

Refactoring: the `moved` block