Platform Engineering · Lesson 129

Terraform Modules and Testing

Lesson 128 taught you to protect the state. This lesson is about sharing the code. A module is a folder of Terraform files with inputs on one side and outputs on the other. Write it once, use it in three environments, and test it before any of them trusts it.

Difficulty: Advanced · Know this first: Lesson 128 — Terraform State and Workspaces

Run it as:

When it breaks, I check

One thing to remember

Where the time goes

Every hop charges rent in milliseconds. The bar below is a worked example for this lesson's scenario — not a measurement from a live system — but the shape is honest: on a cache hit the trip is almost free, on a miss the kitchen eats the budget. Step through the lesson or switch the scenario and watch the bar change.

Extra diagram · from scratch to master

The module, mapped: call, registry, test, plan

Start with one call. Add one box at a time until the same module serves three environments, test included.

7 boxes on the trip3 environments1 breaking change
Root call
0 ms
Registry
10 ms
Module
20 ms
Outputs
5 ms
Test
30 ms
Plan
25 ms
Broken
trip ends
Request / flowResponse · the way backFailure / dead end

Try it: change the inputs and watch the trip bend

The budget bar above shows three fixed stories. This simulator lets you write your own. Move a slider and watch the test, the plan, and the applies change in the budget bar, in the hop timings, and in the total. The numbers are a teaching example, not live measurements. The shape is the lesson: reuse multiplies the work, not the code.

3

How many environments call the same module. Every environment adds its own plan and its own apply. The module is written once. The work is paid once per environment.

20

How many resources the module builds. The plan costs about half a millisecond per resource, and the apply costs about four fifths of a millisecond per resource, in each environment that uses it.

10

How many test cases check the module. Each case costs about 3 ms, and the tests run once, before any environment applies. Ten cases cost about 30 ms. Fifty cost about 150 ms.

Try this: (1) Set environments to 5, resources to 50, test cases to 25. The test is about 75 ms, the plans about 175 ms, the applies about 200 ms, and the total is about 510 ms. (2) Set all three to the worst end: 10 environments, 100 resources, 50 cases. The test is 150 ms, the plans are 600 ms, the applies are 800 ms, and the total is about 1,610 ms. Same module. Only the inputs changed.

Type your own numbers: Get the test under 100 ms and the total under 600 ms. Type 5 environments, 50 resources, 25 test cases, and run it. Then raise the test cases until the test breaks the budget.

Check yourself

Three questions. No score is saved anywhere — this is just you against the material.

Basic to master

I take the same module four times here. First I learn what a module is. Then I learn to wire modules together. Then I learn to test and version them. Last I run them for the whole organisation.

Basic — One module, one call

Definition: A module is a folder of Terraform files with inputs and outputs. The root calls it with a module block, passes variables in, and reads outputs back. The module builds the resources. The root never sees the inside. A local module is a folder path. A registry module is a name and a version.

Types:

  • Local modules, a folder beside the root, no version, good for learning.
  • Registry modules, versioned and shared, good for teams.
  • Git modules, pinned by a tag or a commit, good for private sharing.
  • Root modules, the top level that calls everything else.

Uses: I use a module the second time I write the same resources. The first time is a copy. The second time is a module. I keep the module small: one thing, done well.

Dimensions: At low traffic everything is nearly free. What breaks first is the copy: two copies of the same code that drift apart. It costs almost nothing to turn the second copy into a module. It costs a week when the copies disagree in prod.

Try it yourself

Make a folder called tf-module. Save the first file as modules/web/main.tf and the second as main.tf. The module takes a name and a server count and gives back the count.

variable "name" {
  type = string
}
variable "servers" {
  type    = number
  default = 2
}
output "server_count" {
  value = var.servers
}
variable "servers" {
  type    = number
  default = 2
}

module "web" {
  source  = "./modules/web"
  name    = "checkout"
  servers = var.servers
}

output "count" {
  value = module.web.server_count
}
terraform init -backend=false
terraform validate
terraform fmt -check

What you should see: Success! The configuration is valid. The fmt check prints nothing.

It passes when: validate prints the success line. The module is local, so no registry and no network are involved.

Intermediate — Inputs, outputs, and composition

Definition: A good module declares its inputs with types, descriptions, and defaults, and returns outputs the caller can use. Composition means modules calling modules: a network module feeds a server module, which feeds a load balancer module. The root wires them together with outputs.

Types:

  • Input variables, typed, described, with defaults that mean something.
  • Outputs, the public face, named for what they are, not for how they are built.
  • Locals, the private workings, which callers never see.
  • Composition, small modules wired together instead of one big module.

Uses: I use composition when a stack has clear parts: network, servers, load balancer. I use outputs to pass ids between modules, so nothing is hardcoded. I use variable validation to reject a bad input at plan time, when it is cheap.

Dimensions: As the module grows, the inputs grow, and the contract gets harder to hold in your head. What breaks is the input list: twenty variables, half of them optional, and nobody knows which ones matter. It costs a smaller module and a written contract. The trade is that composition adds wiring, and wiring is work.

Try it yourself

Change the server count in main.tf from 2 to 3 and run plan. The module has no cloud resources, so the plan only shows the output changing.

sed -i 's/default = 2/default = 3/' main.tf
terraform plan
sed -i 's/default = 3/default = 2/' main.tf

What you should see:

Changes to Outputs:
  + count = 3

It passes when: the plan shows the output changing from 2 to 3 and nothing else. Change it back when you are done.

Advanced — Testing, versioning, and the registry

Definition: Terraform test runs a module against mock providers and asserts the claims: resources exist, outputs have values, counts are right. Versioning says what a change means: a patch fixes a bug, a minor change adds a feature, a major change breaks callers. The registry is where versioned modules live, with docs generated from the code.

Types:

  • Unit tests, which run the module with mocks and check the outputs.
  • Integration tests, which apply the module in a throwaway environment and check the real cloud.
  • Semantic versions, where the number tells callers how safe the upgrade is.
  • A private registry, where the team's modules live with their docs.

Uses: I use tests on every shared module, and I run them in the pipeline on every change. I use semantic versions so a rename is a major version, not a surprise. I use the registry docs as the contract, because the docs are generated from the code and cannot lie for long.

Dimensions: At ten times the modules, testing is the bottleneck, not writing. What breaks is the untested module that everyone depends on. It costs a test run in the pipeline and a version bump discipline. The trade is that tests slow down a change and speed up every change after it.

Try it yourself

Save this file as web.tftest.hcl. It runs the module with mock providers, so it never touches the cloud. Two run blocks: the default count, and the count when asked for three.

mock_provider "aws" {}

run "two_servers_by_default" {
  command = plan
  assert {
    condition     = module.web.server_count == 2
    error_message = "expected 2 servers"
  }
}

run "three_servers_when_asked" {
  command = plan
  variables {
    servers = 3
  }
  assert {
    condition     = module.web.server_count == 3
    error_message = "expected 3 servers"
  }
}
terraform test

What you should see:

Read the flags: terraform init -backend=false, terraform validate, terraform fmt -check, and terraform test

Four commands, one habit. Init sets up, validate checks the logic, fmt checks the shape, and test proves the module does what it claims.

  • terraform init -backend=false: This sets up the directory without touching a backend. The -backend=false part skips the remote backend, so the test runs with no cloud and no state.
  • terraform validate: This checks syntax and references. It never calls the cloud. A module that fails validate fails fast, before any test runs.
  • terraform fmt -check: This reports files that need formatting and exits non-zero. The -check part means report only, do not rewrite. In CI the report is the gate.
  • terraform test: This runs the test files next to the module. Each run block plans the module and asserts on the outputs. A failing assert fails the run.
  • -filter (added): The lesson did not show this one yet. It runs one test file only, like terraform test -filter=tests/basic.tftest.hcl. I use it when one file is slow and I am fixing one thing.

Try it: save the test file next to a module and run terraform test. Expect a pass. Rename one output in the module and run it again. Expect a failure that names the output.

web.tftest.hcl... pass

Success! 2 passed, 0 failed.

It passes when: the test prints 2 passed, 0 failed. That is the module proving its own contract: the default is 2, and an explicit 3 comes back as 3.

A test that catches the rename. A module rename breaks every caller that uses the old output name. A test catches it before the callers do. I write the test first when I rename anything in a shared module, and the pipeline runs it on every change.

Do this: save the test file from the snippet next to a module and run terraform test. Expected: a pass. Rename one output in the module and run the test again. Expected: a failure that names the output. Rename it back and the test passes again.

mock_provider "aws" {}

run "network_outputs_exist" {
  command = plan

  assert {
    condition     = output.vpc_id != ""
    error_message = "vpc_id output must not be empty"
  }
}

What the snippet means: the mock provider answers without touching the cloud, and the assert checks the contract. A test like this costs ten lines and saves a broken afternoon for every caller.

The variable with no validation. A variable with no validation accepts anything, including the value that builds a public bucket or a subnet that overlaps another network. The validation block rejects the bad value at plan time, with a message the caller can act on.

Do this: add the validation block from the snippet to a CIDR variable, then run terraform plan -var='cidr_block=10.0.0.0/8'. Expected: the plan fails before it talks to the cloud, and the error says the CIDR must be a /16. Pass a /16 and the plan proceeds.

Read the flags: terraform plan -var

A variable is an input. The -var flag sets one input from the command line, so I can test a bad value without editing any file.

  • -var='cidr_block=10.0.0.0/8': This sets the cidr_block variable to 10.0.0.0/8 for this run only. The quotes keep the shell from splitting the value. The file on disk does not change.
  • -var-file (added): The lesson did not show this one yet. It loads variables from a file, like terraform plan -var-file=prod.tfvars. I use it when a run needs ten variables, because ten -var flags are unreadable.

Try it: add the validation block to a CIDR variable, then run terraform plan -var='cidr_block=10.0.0.0/8'. Expect the plan to fail before it talks to the cloud, because the value is out of range.

variable "cidr_block" {
  type        = string
  description = "CIDR block for the VPC, must be a /16."

  validation {
    condition     = can(cidrnetmask(var.cidr_block)) && tonumber(split("/", var.cidr_block)[1]) == 16
    error_message = "cidr_block must be a /16 network."
  }
}

What the snippet means: validation runs before any resource is planned. A bad value fails fast, in the caller, with a message that says what is wrong instead of a cloud error three steps later.

Master — Modules for an organisation

Definition: At this level modules are a platform. A small set of blessed modules, tested and versioned, that every team uses. Policy checks on the plan before it applies. A module review process, the way code review works for libraries. And a deprecation path, so an old module can retire without breaking its callers overnight.

Types:

  • Blessed modules, the short list every team is asked to use.
  • Policy as code, which rejects a plan that breaks the rules.
  • Deprecation, where an old version warns before it stops working.
  • Module metrics, which show who uses what, and which modules are stale.

Uses: I use this when more than one team builds in the same cloud account, or when a bad module can reach every environment at once. It is also how I review a setup I did not build: I ask which modules are blessed, which are stale, and what happens when one changes.

Dimensions: At a hundred times the modules the registry is not the bottleneck, the trust is. What breaks is the blessed module that nobody owns, or the breaking change that shipped as a patch. It costs real operational work: ownership, review, and deprecation. The trade is that shared code is a platform, and a platform needs owners.

Try it yourself

Save this script as pin-check.py. It reads every .tf file and fails on any module from a registry that has no version pin. Local modules are exempt, because a local path is already the pin.

#!/usr/bin/env python3
"""Every module from a registry must pin a version. Local modules are exempt."""
import glob, re, sys
bad = []
for path in glob.glob("**/*.tf", recursive=True):
    text = open(path).read()
    for m in re.finditer(r'module\s+"[^"]+"\s*\{(.*?)\}', text, re.S):
        body = m.group(1)
        src = re.search(r'source\s*=\s*"([^"]+)"', body)
        if src and not src.group(1).startswith(("./", "../")):
            if not re.search(r'version\s*=', body):
                bad.append(f"{path}: module from {src.group(1)} has no version pin")
if bad:
    print("FAIL")
    for b in bad:
        print("  - " + b)
    sys.exit(1)
print("PASS: every registry module pins a version")
python3 pin-check.py

What you should see: PASS: every registry module pins a version

Read the flags: python3 pin-check.py and python3 - with a heredoc

A check script is a small program I run, not a command I memorise. The two forms here do the same job two ways: a file, and code typed straight into the terminal.

  • python3 pin-check.py: This runs the file pin-check.py. Python3 is the interpreter, and the file name is the program. No flag is needed, because a file name is the default input.
  • python3 -: The dash means read the program from standard input instead of a file. It is how a heredoc feeds code to Python.
  • <<'PYEOF': This is a heredoc. It sends every line until PYEOF as input. The quotes around PYEOF stop the shell from expanding variables inside the code, so the Python stays exactly as written.
  • python3 -c (added): The lesson did not show this one yet. The -c flag runs one code string, like python3 -c "print('hi')". I use it for one-line checks and the heredoc for anything longer.

Try it: run python3 pin-check.py, then change one module version to unpinned and run it again. Expect PASS first, then a failure that names the module.

It passes when: the script prints PASS on this folder. Try it on a folder with an unpinned registry module and watch it fail with the module name. A version number that does not say how scared to be is decoration.

Every variable needs a description. A variable with no description is a variable the next person has to guess, and guessing is how a small server becomes a large bill. I check for missing descriptions in the pipeline, the same way I check for a failing test.

Do this: run the check in the snippet against a module folder. Expected: a list of variables with no description, or an empty list. An empty list is the pass. Add a description to each one the check finds, and run it again.

python3 - <<'PYEOF'
import re, pathlib
for f in sorted(pathlib.Path(".").glob("*.tf")):
    text = f.read_text()
    for m in re.finditer(r'variable\s+"([^"]+)"\s*\{(.*?)\n\}', text, re.S):
        if "description" not in m.group(2):
            print(f"{f}:{m.group(1)} has no description")
PYEOF

What the snippet means: the script reads every variable block and reports the ones with no description. It is a small check, and it is the one that keeps the registry docs honest.

Deprecation without breaking callers. An output that forty callers use cannot just disappear. I keep the old output working, add the new one beside it, and mark the old one as deprecated in its description. Callers move on their own schedule, and the old output retires in a major version.

Do this: add the two outputs from the snippet to a module and run terraform plan. Expected: both values in the output. Callers that read the old name still work. The description is the warning, and the major version bump is the deadline.

output "vpc_id" {
  description = "The VPC id. Use network_id instead; vpc_id is deprecated and will be removed in v3."
  value       = aws_vpc.main.id
}

output "network_id" {
  description = "The VPC id."
  value       = aws_vpc.main.id
}

What the snippet means: both outputs read the same resource, so nothing breaks today. The description carries the migration, and the version number carries the deadline.

Go deeper

A module's inputs are its contract, and the contract deserves the same care as an API. Type every variable. Describe every variable. Give defaults only where the default is genuinely the normal case. A variable with no description is a variable the next person has to guess, and guessing is how a small server becomes a large bill.

Outputs are the public face. Name them for what they are, not for how they are built. A load balancer address is an address, not an elb_dns_name. The name survives refactors. The implementation does not. And never rename an output in a shared module without a major version bump. The rename is the breaking change, even if the resources are identical.

Terraform test runs the module with mock providers. You write run blocks that set the inputs, and assertions that check the outputs. The test does not touch the cloud, so it runs in seconds and in the pipeline. It catches the renamed output, the missing default, the count that is off by one. It does not catch a cloud that disagrees with the mocks. That is what a throwaway environment is for.

Versioning is a promise, and semantic versions are the language of that promise. A patch fixes a bug and changes nothing else. A minor version adds something new and breaks nothing. A major version breaks callers, and it says so in the number. When a team upgrades a module, the version number should tell them how scared to be. If it does not, the versioning is decoration.

Composition is how small modules become a platform. A network module outputs a network id. A server module takes it as an input. A load balancer module takes the server ids. The root wires them together. No module knows about the others. The root is the only place that knows the whole shape. That is the design: small pieces, one wiring diagram.

At 10x the modules, the shape holds and the numbers grow. The registry gets bigger, the tests get slower, the version bumps get more careful. At 100x, the design changes: a short list of blessed modules, a review process for new ones, and a deprecation path for old ones. The module never stops being a folder of files. It just gets more callers.

module "web" {
  source  = "registry.example.com/web/aws"
  version = "2.1.0"

  name    = "checkout"
  servers = 2
  size    = "medium"
}

What the snippet means: the root calls a module from the registry, pinned to version 2.1.0, and passes three inputs. The module builds the web stack. The root never sees the resources inside. Those seven lines are the whole call, and the version is the promise that the code will not change under me.

Try it yourself

Prove the output contract with a test. Rename the output in the module and run the test. The test must fail before the change ships, not after.

sed -i 's/output "server_count"/output "count_of_servers"/' modules/web/main.tf
terraform test
sed -i 's/output "count_of_servers"/output "server_count"/' modules/web/main.tf
terraform test

What you should see: the first test prints Failure! 0 passed, 1 failed, 1 skipped. The second prints Success! 2 passed, 0 failed.

It passes when: the rename fails the test and the restore passes it. That is the contract: the test checks the output by name, so a rename fails the test before it ships.

Test the module, not the cloud

An integration test that applies real resources is slow and costs money. A mock test is fast and free, and it catches the mistakes I actually make: a missing output, a wrong count, a variable that never reaches the resource. I run mock tests on every shared module.

Do this: write a test file with two run blocks, one that plans the module with default values and asserts the outputs exist, and one that plans it with a custom CIDR and asserts the output matches. Run terraform test. Expected: both runs pass. Break one assert on purpose, run it again, and expect the failure to name the assert, not the module.

mock_provider "aws" {}

run "defaults" {
  command = plan

  assert {
    condition     = output.vpc_id != ""
    error_message = "vpc_id must be set with defaults"
  }
}

run "custom_cidr" {
  command = plan

  variables {
    cidr_block = "10.30.0.0/16"
  }

  assert {
    condition     = output.cidr_block == "10.30.0.0/16"
    error_message = "cidr_block output must match the input"
  }
}

What the snippet means: the two runs test the contract twice, once with defaults and once with a custom value. The mock provider means the whole test runs in seconds, with no cloud bill.

One time it broke

What broke

A shared module I depended on shipped a renamed output as a patch version. The change looked small: one output name, cleaned up. Every root that read the old name broke at plan time. Three environments failed to plan, and one pipeline failed in the middle of a deploy window.

Timeline

  • 09:10,the module author merged a cleanup: an output renamed from a short name to a clearer one, released as version 1.4.1.
  • 09:22,the pipeline in the first environment picked up the new version and the plan failed: the output it read no longer existed.
  • 09:30,the second and third environments failed the same way. Three plans, one cause.
  • 09:41,I read the module changelog. The rename was listed as a cleanup, not a breaking change. The version number said patch. The code said major.
  • 10:05,I pinned all three roots back to version 1.4.0 and the plans went green.
  • 10:30,the module author released version 2.0.0 with the rename, and the roots upgraded one at a time, on purpose.

What changed after

Three things. First, a rename is a major version, always, with no exceptions for cleanups. Second, the pipeline pins every module version, and an unpinned module fails the pipeline before it plans. Third, the module's tests now check every output by name, so a rename fails the test before it ships.

Replay it yourself

Replay the rename from the incident. Rename the output, run validate, and read the error. Then restore the name and confirm the plan is green again.

sed -i 's/output "server_count"/output "count_of_servers"/' modules/web/main.tf
terraform validate
sed -i 's/output "count_of_servers"/output "server_count"/' modules/web/main.tf
terraform validate

What you should see: the first validate prints Error: Unsupported attribute and names module.web.server_count on main.tf line 7. The second prints Success! The configuration is valid.

It passes when: the error names the exact output and line, and the restore prints the success line. The rename was one word. The rule it broke is the version rule: a rename is a major version, so it ships as 2.0.0, never as a patch.

If you remember nothing else

Design exercise

Design a shared Terraform module for a web stack used by five teams in three environments each. The stack is a network, two servers, and a load balancer. Teams need different sizes and different server counts. A breaking change must never reach prod by surprise, and a team must be able to use last month's version while another team uses this month's.

Clarifying questions to ask

  • What are the module's inputs, and which ones have defaults? What does each default mean?
  • What are the outputs, and who reads them? What happens if one is renamed?
  • How is the module versioned, and what does each version number promise the callers?
  • How is the module tested, and what does the test check: resources, outputs, or both?
  • What is the upgrade path: how does a team move from version 1 to version 2, and who decides when?

Rough sizing

Start with the budget from this lesson. Call 0, registry 10, inputs 5 per environment set, module 20, outputs 5 per environment set, test 3 per case, plan 10 plus half a millisecond per resource per environment, applies about four fifths of a millisecond per resource per environment. For 3 environments, 20 resources, and 10 test cases that is about 30 for the test, 60 for the plans, 48 for the applies, and 60 for the fixed hops, about 198 ms in this teaching example. The real cost is not the milliseconds, it is the coordination: fifteen callers of one module means fifteen teams to warn before a breaking change.

Trade-offs to name

One shared module buys consistency and costs coordination: every change is a change for fifteen callers. Many small modules buy independence and cost wiring: the root has to connect them. Semantic versions buy a warning system and cost discipline: someone has to decide what counts as breaking. Tests buy safety and cost time in the pipeline. And the target is trust, not coverage. A module teams trust gets used. A module they do not trust gets copied, and the copies drift.

Build it: the checkable version

Build the web stack module from the exercise: one module called three times, once per environment, with different server counts. Then test it and pin-check it.

Steps:

  • Build the module from the Basic section: modules/web/main.tf.
  • Save the root below as main.tf. It calls the module for dev, staging, and prod.
  • Save the test file as web.tftest.hcl and the pin script as pin-check.py.
module "dev" {
  source  = "./modules/web"
  name    = "checkout-dev"
  servers = 1
}

module "staging" {
  source  = "./modules/web"
  name    = "checkout-staging"
  servers = 2
}

module "prod" {
  source  = "./modules/web"
  name    = "checkout-prod"
  servers = 3
}

output "dev_count" {
  value = module.dev.server_count
}

output "staging_count" {
  value = module.staging.server_count
}

output "prod_count" {
  value = module.prod.server_count
}
mock_provider "aws" {}

run "each_environment_gets_its_count" {
  command = plan
  assert {
    condition     = module.dev.server_count == 1
    error_message = "dev should have 1 server"
  }
  assert {
    condition     = module.staging.server_count == 2
    error_message = "staging should have 2 servers"
  }
  assert {
    condition     = module.prod.server_count == 3
    error_message = "prod should have 3 servers"
  }
}
terraform init -backend=false
terraform validate
terraform fmt -check
terraform test
python3 pin-check.py

What you should see: Success! The configuration is valid., fmt prints nothing, Success! 1 passed, 0 failed., and PASS: every registry module pins a version.

It passes when: the test prints 1 passed, validate prints the success line, fmt prints nothing, and the pin check prints PASS. That is the exercise, built: one module, three environments, each with its own count, and a test that proves the counts. A team that wants last month's version pins it by number, and the pin check is what enforces that.

Next in this series
Lesson 110 — Ansible