Lesson 06 intermediate

Terraform Modules

Package infrastructure into reusable modules, call them from local folders, Git or the Registry, pin versions, test them with terraform test and use the 1.15 and 1.16 additions such as const sources and import blocks inside modules.

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

SourceExample
Local foldersource = "./modules/cache"
Terraform Registrysource = "terraform-aws-modules/vpc/aws" plus version = "~> 6.0"
Private registry (HCP Terraform)source = "app.terraform.io/orbit/cache/docker"
Git over HTTPSsource = "git::https://github.com/orbit/tf-modules.git//cache?ref=v1.4.0"
Git over SSHsource = "git::ssh://git@github.com/orbit/tf-modules.git//cache?ref=v1.4.0"
S3 bucket or archive URLsource = "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 moved blocks 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, import blocks 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

TaskSyntax or command
Call a local modulemodule "x" { source = "./modules/cache" }
Call a registry modulesource = "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 outputmodule.api_cache.address
Download new or changed modulesterraform init (or terraform init -upgrade)
Run module teststerraform test
Run one test fileterraform 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?

  1. Reference module.api_cache.docker_container.this.id directly
  2. Read it from the module’s variables
  3. Add an output for the ID to the module and reference module.api_cache.<output>
  4. Use a data source pointing at the module folder
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?

  1. Git sources only work over SSH
  2. Every init can pull a different version of the module, so plans change without any code change in your repository
  3. Terraform refuses to download modules without a ref
  4. The module will be downloaded on every plan, which is slow
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 .tf files; 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: version for registries, ?ref= for Git.
  • Reusable modules set minimum provider versions; the root module chooses the exact one.
  • terraform test with mock providers checks modules in seconds, with no infrastructure.
  • 1.15 adds const variables in module sources and deprecations; 1.16 allows import blocks 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.

↑ ↓ navigate Enter open Esc close