A module is a folder of .tf files. That is the whole definition. The folder where you run terraform is the root module; any other module it calls is a child module. Modules let you write “an Orbit service with a container, a health check and a cache” once, and stamp it out for every service and environment with a few lines.
When to write a module
Write a module when a group of resources always travels together and you need it more than once: a service container plus its network attachment and volume, a VPC with its subnets, a bucket with the encryption and policies your company requires.
Do not wrap a single resource in a module just to rename its arguments. That adds a layer to read without adding meaning. A good module has an opinion: it encodes how your team builds something.
A module from scratch
Orbit needs a Valkey cache (the open-source Redis fork) for the API, and later one for sessions. Create this layout:
orbit-local/
├── main.tf
└── modules/
└── cache/
├── main.tf
├── variables.tf
└── outputs.tf
modules/cache/variables.tf is the module’s public interface:
variable "name" {
description = "Cache name, for example orbit-dev-api-cache."
type = string
}
variable "network" {
description = "Docker network the cache joins."
type = string
}
variable "max_memory_mb" {
description = "Memory limit for the cache."
type = number
default = 128
validation {
condition = var.max_memory_mb >= 64 && var.max_memory_mb <= 2048
error_message = "max_memory_mb must be between 64 and 2048."
}
}
modules/cache/main.tf holds the resources:
terraform {
required_providers {
docker = {
source = "kreuzwerker/docker"
version = ">= 4.0"
}
}
}
resource "docker_image" "valkey" {
name = "valkey/valkey:8-alpine"
keep_locally = true
}
resource "docker_container" "this" {
name = var.name
image = docker_image.valkey.image_id
memory = var.max_memory_mb
command = ["valkey-server", "--maxmemory", "${var.max_memory_mb - 16}mb", "--maxmemory-policy", "allkeys-lru"]
networks_advanced {
name = var.network
aliases = [var.name]
}
}
modules/cache/outputs.tf is what callers can use:
output "address" {
description = "host:port other containers use to reach the cache."
type = string
value = "${var.name}:6379"
}
Notice the module declares a minimum provider version (>= 4.0), not a tight ~> range. The root module decides the exact version; reusable modules should accept as wide a range as they actually work with.
Calling the module
In the root main.tf:
module "api_cache" {
source = "./modules/cache"
name = "orbit-${var.environment}-api-cache"
network = docker_network.orbit.name
max_memory_mb = 256
}
module "session_cache" {
source = "./modules/cache"
name = "orbit-${var.environment}-sessions"
network = docker_network.orbit.name
}
resource "docker_container" "api" {
name = "orbit-${var.environment}-api"
image = docker_image.api.image_id
env = ["CACHE_ADDR=${module.api_cache.address}"]
# ...
}
Run terraform init after adding a module, then plan. Resources inside modules get addresses such as module.api_cache.docker_container.this. Everything inside a module is private: the root can only read what the module puts in outputs.
Module sources
| Source | Example |
|---|---|
| Local folder | source = "./modules/cache" |
| Terraform Registry | source = "terraform-aws-modules/vpc/aws" plus version = "~> 6.0" |
| Private registry (HCP Terraform) | source = "app.terraform.io/orbit/cache/docker" |
| Git over HTTPS | source = "git::https://github.com/orbit/tf-modules.git//cache?ref=v1.4.0" |
| Git over SSH | source = "git::ssh://git@github.com/orbit/tf-modules.git//cache?ref=v1.4.0" |
| S3 bucket or archive URL | source = "s3::https://s3.amazonaws.com/orbit-modules/cache-1.4.0.zip" |
The //cache part selects a subfolder of the repository. Always pin: a version constraint for registry modules, a tag or commit in ?ref= for Git. An unpinned module changes under your feet the next time someone runs init.
Choosing a module source per environment
Since Terraform 1.15, a module source can use variables marked const = true. Const variables must be known during init, which is when modules are downloaded:
variable "cache_module_ref" {
type = string
const = true
default = "v1.4.0"
}
module "api_cache" {
source = "git::https://github.com/orbit/tf-modules.git//cache?ref=${var.cache_module_ref}"
# ...
}
Run terraform init again after the value changes, so the new release is downloaded. This keeps the module reference in one obvious place instead of repeated in every module block, and lets each environment move to a new module release at its own pace. Only const variables work here; a normal variable or a local in source is still an error at init.
Using Registry modules wisely
The public Registry has thousands of modules, and some, like the terraform-aws-modules collection, are excellent. Before adopting one, check:
- Maintenance: recent releases, open issues answered, support for your provider’s current major version.
- Size: some modules expose 200 inputs to cover every case. If you use five of them, a small module of your own may be easier to read.
- Ownership: a module you depend on is code you run with admin rights. Pin it and read the changelog before upgrading.
Testing a module with terraform test
terraform test (Terraform 1.6+) runs .tftest.hcl files from a tests/ folder. Each run block plans or applies the module and checks assertions. With a mock provider (1.7+), the test needs no Docker and no cloud at all:
# modules/cache/tests/cache.tftest.hcl
mock_provider "docker" {}
variables {
name = "test-cache"
network = "test-net"
}
run "address_uses_name_and_default_port" {
command = plan
assert {
condition = output.address == "test-cache:6379"
error_message = "address must be <name>:6379."
}
}
run "rejects_tiny_memory" {
command = plan
variables {
max_memory_mb = 16
}
expect_failures = [var.max_memory_mb]
}
$ cd modules/cache
$ terraform init
$ terraform test
tests/cache.tftest.hcl... in progress
run "address_uses_name_and_default_port"... pass
run "rejects_tiny_memory"... pass
tests/cache.tftest.hcl... tearing down
tests/cache.tftest.hcl... pass
Success! 2 passed, 0 failed.
The second test proves that the validation rule rejects bad input. Run these tests in CI on every pull request that touches the module (lesson 14).
Changing a module without breaking callers
- Renaming resources inside a module: add
movedblocks inside the module itself, so every caller’s next plan moves instead of recreating. - Renaming inputs or outputs: keep the old one with
deprecated = "..."(1.15) for a release, then remove it. - Adopting existing objects: since Terraform 1.16,
importblocks can live inside a module, so a module can ship the import of a resource that existed before it. - Releasing: tag versions with semantic versioning (
v1.4.0), and bump the major version for anything that forces callers to change code or recreates resources.
Quick reference
| Task | Syntax or command |
|---|---|
| Call a local module | module "x" { source = "./modules/cache" } |
| Call a registry module | source = "terraform-aws-modules/vpc/aws", version = "~> 6.0" |
| Pin a Git module | ?ref=v1.4.0 at the end of the source |
| Read a module output | module.api_cache.address |
| Download new or changed modules | terraform init (or terraform init -upgrade) |
| Run module tests | terraform test |
| Run one test file | terraform test -filter=tests/cache.tftest.hcl |
| Evaluate expressions inside a module (1.16) | terraform console -scope=module.api_cache |
Exercise
The root module needs the cache’s container ID, but the cache module has no output for it. What can the root do?
Show answer
Answer: C. Module internals are private. The only way for a caller to read a value from a module is through that module’s outputs.
Exercise
A teammate writes source = “git::https://github.com/orbit/tf-modules.git//cache” with no ref. What is the risk?
Show answer
Answer: B. Without a ref, Terraform takes the default branch as it is at init time. Pin a tag or commit so module upgrades are deliberate, reviewed changes.
Key takeaways
- A module is a folder of
.tffiles; its variables are the inputs and its outputs the only way out. - Write modules for groups of resources that travel together, not to rename one resource.
- Always pin module versions:
versionfor registries,?ref=for Git. - Reusable modules set minimum provider versions; the root module chooses the exact one.
terraform testwith mock providers checks modules in seconds, with no infrastructure.- 1.15 adds const variables in module sources and deprecations; 1.16 allows
importblocks inside modules.
FAQ
How big should a module be?
Big enough to hide a real decision, small enough to describe in one sentence. “A service container with its cache and health check” is a good module. “All of production” is a configuration, not a module.
Can modules call other modules?
Yes, but keep nesting shallow (two levels at most). Deep trees make plans hard to read and changes hard to trace. Many teams prefer a flat root module that composes several small modules.
Should modules contain provider blocks?
No. Reusable modules declare required_providers and inherit provider configurations from the caller. Provider blocks inside a module make it impossible to use with count or for_each and hard to remove later.
What is the difference between terraform test and tools like Terratest?
terraform test is built in and written in HCL, and works well for plan-level checks and short apply tests. Terratest is a Go library for longer end-to-end tests, such as calling an HTTP endpoint after deploying. Many teams use terraform test for every module and Terratest only for a few critical flows.