Writing and Using Modules
Turn copy-pasted Terraform into reusable modules: inputs, outputs and versions.tf, for_each over modules, composition, registry and git sources, and moved blocks.
By The Dark DebuggerUpdated 30 min read
A module is how you stop copy-pasting Terraform. This tutorial takes a flat
configuration that issues TLS certificates for internal services, extracts it into
two modules, calls one of them once per service with for_each, and moves the
existing resources into the modules without reissuing a single certificate. Then it
covers module sources (local paths, the public registry, git tags) and tests a
popular registry module offline with a mocked AWS provider. You should be comfortable
with variables and outputs,
for_each and moved blocks from
Terraform State.
Why modules
Here's a realistic starting point. A platform team runs a small internal certificate
authority with Terraform: one CA, and a certificate for each service that needs
mutual TLS. The tls provider does the cryptography locally, and local_file
writes the PEM files, so you can run all of it without a cloud account.
terraform {
required_version = ">= 1.5"
required_providers {
tls = { source = "hashicorp/tls", version = "~> 4.0" }
local = { source = "hashicorp/local", version = "~> 2.5" }
}
}
# ---- The internal certificate authority
resource "tls_private_key" "ca" {
algorithm = "ECDSA"
ecdsa_curve = "P384"
}
resource "tls_self_signed_cert" "ca" {
private_key_pem = tls_private_key.ca.private_key_pem
is_ca_certificate = true
validity_period_hours = 5 * 365 * 24
allowed_uses = ["cert_signing", "crl_signing"]
subject {
common_name = "Acme Internal CA"
organization = "Acme Corp"
}
}
resource "local_file" "ca_cert" {
filename = "${path.module}/certs/ca.crt"
content = tls_self_signed_cert.ca.cert_pem
file_permission = "0644"
}
# ---- Certificate for the api service
resource "tls_private_key" "api" {
algorithm = "ECDSA"
ecdsa_curve = "P256"
}
resource "tls_cert_request" "api" {
private_key_pem = tls_private_key.api.private_key_pem
dns_names = ["api.internal.acme.example", "api"]
subject {
common_name = "api"
organization = "Acme Corp"
}
}
resource "tls_locally_signed_cert" "api" {
cert_request_pem = tls_cert_request.api.cert_request_pem
ca_cert_pem = tls_self_signed_cert.ca.cert_pem
ca_private_key_pem = tls_private_key.ca.private_key_pem
validity_period_hours = 90 * 24
allowed_uses = ["digital_signature", "key_encipherment", "server_auth", "client_auth"]
}
resource "local_file" "api_cert" {
filename = "${path.module}/certs/api.crt"
content = tls_locally_signed_cert.api.cert_pem
file_permission = "0644"
}
resource "local_sensitive_file" "api_key" {
filename = "${path.module}/certs/api.key"
content = tls_private_key.api.private_key_pem
file_permission = "0600"
}terraform init
terraform apply -auto-approve
terraform state list
openssl verify -CAfile certs/ca.crt certs/api.crt[…]
Apply complete! Resources: 8 added, 0 changed, 0 destroyed.
local_file.api_cert
local_file.ca_cert
local_sensitive_file.api_key
tls_cert_request.api
tls_locally_signed_cert.api
tls_private_key.api
tls_private_key.ca
tls_self_signed_cert.ca
certs/api.crt: OKIt works, and openssl agrees the certificate chains to the CA. Now the billing
team needs a certificate. The flat approach means copying five resource blocks and
renaming fifteen references, and the ledger team will want the same next month. Each
copy is a chance to forget file_permission = "0600" on a private key. A module
turns those five blocks into one block per service, with the rules written down
once.
Every directory is a module
Terraform's definition is simple: a module is a directory of .tf files. The
directory you run terraform in is the root module. A module block in it calls a
child module, which is just another directory, and passes it input variables:
module "billing_cert" {
source = "./modules/service-cert"
service_name = "billing"
# ... the module's other input variables
}source says where the code lives. Everything else in the block sets the child
module's variables. Inside the child, resources can't see anything from the caller
except those variables, and the caller can't see anything inside the child except
its outputs. That boundary is the point: it's a function call, with arguments and a
return value.
Writing a module
The layout below is the convention you'll see in nearly every published module.
Terraform doesn't require any of these file names (it reads every .tf file in the
directory), but sticking to them means anyone can find the inputs of any module
without reading all of it.
.
├── main.tf
├── modules
│ └── service-cert
│ ├── README.md
│ ├── main.tf
│ ├── outputs.tf
│ ├── variables.tf
│ └── versions.tf
└── terraform.tfstate| File | Contents |
|---|---|
variables.tf | Every input, each with description, type, and validation where it helps |
main.tf | The resources |
outputs.tf | Everything a caller may read, each with a description |
versions.tf | required_version and required_providers, with minimum versions only |
README.md | What it does, a usage example, inputs and outputs |
variables.tf: the module's contract
variable "service_name" {
description = "Short service name. Used as the certificate's common name and the file name prefix."
type = string
validation {
condition = can(regex("^[a-z][a-z0-9-]{1,30}$", var.service_name))
error_message = "service_name must be 2-31 lowercase letters, digits or hyphens, starting with a letter."
}
}
variable "dns_names" {
description = "DNS names the certificate is valid for."
type = list(string)
}
variable "ca_cert_pem" {
description = "PEM-encoded certificate of the CA that signs this certificate."
type = string
}
variable "ca_private_key_pem" {
description = "PEM-encoded private key of the signing CA."
type = string
sensitive = true
}
variable "validity_days" {
description = "Certificate lifetime in days."
type = number
default = 90
validation {
condition = var.validity_days >= 1 && var.validity_days <= 397
error_message = "validity_days must be between 1 and 397."
}
}
variable "output_dir" {
description = "Directory to write <service_name>.crt and <service_name>.key into."
type = string
}A few choices worth copying:
- Validation lives in the module. The caller gets a clear error at plan time, instead of a malformed certificate or a confusing provider error later.
- Defaults only where there's a right answer. 90 days is a sensible lifetime for an internal certificate. There is no sensible default CA or output directory, so those are required.
sensitive = trueon the CA key, so Terraform redacts it in plan output.
main.tf: the resources
The five resources from the flat file, with the hard-coded values replaced by
variables. Single-instance resources inside a module are conventionally named this
(we'll revisit that choice in the exercises):
resource "tls_private_key" "this" {
algorithm = "ECDSA"
ecdsa_curve = "P256"
}
resource "tls_cert_request" "this" {
private_key_pem = tls_private_key.this.private_key_pem
dns_names = var.dns_names
subject {
common_name = var.service_name
organization = "Acme Corp"
}
}
resource "tls_locally_signed_cert" "this" {
cert_request_pem = tls_cert_request.this.cert_request_pem
ca_cert_pem = var.ca_cert_pem
ca_private_key_pem = var.ca_private_key_pem
validity_period_hours = var.validity_days * 24
allowed_uses = ["digital_signature", "key_encipherment", "server_auth", "client_auth"]
}
resource "local_file" "cert" {
filename = "${var.output_dir}/${var.service_name}.crt"
content = tls_locally_signed_cert.this.cert_pem
file_permission = "0644"
}
resource "local_sensitive_file" "key" {
filename = "${var.output_dir}/${var.service_name}.key"
content = tls_private_key.this.private_key_pem
file_permission = "0600"
}outputs.tf: what callers may read
output "cert_path" {
description = "Path of the PEM certificate file."
value = local_file.cert.filename
}
output "key_path" {
description = "Path of the PEM private key file (mode 0600)."
value = local_sensitive_file.key.filename
}
output "expires_at" {
description = "RFC 3339 timestamp when the certificate expires."
value = tls_locally_signed_cert.this.validity_end_time
}
output "cert_pem" {
description = "The signed certificate, PEM-encoded."
value = tls_locally_signed_cert.this.cert_pem
}Output anything a caller might reasonably need: identifiers, paths, ARNs, endpoints. Adding an output later is harmless, but a caller who needs one you didn't expose has to fork your module.
versions.tf: minimums, not pins
terraform {
required_version = ">= 1.5"
required_providers {
tls = { source = "hashicorp/tls", version = ">= 4.0" }
local = { source = "hashicorp/local", version = ">= 2.4" }
}
}Notice >= here, while the root configuration uses ~> 4.0. A module declares the
oldest provider versions it works with. The root module, which is what actually gets
deployed, pins the exact range, and the lock file records the exact version. If a
module pinned ~> 4.0 and another module pinned ~> 5.0, no root configuration
could use both.
There's also something missing on purpose: a provider "tls" {} block. Child modules
inherit provider configurations from the root. A provider block inside a reusable
module is a bug waiting to happen, because the caller can no longer choose the
region, the account or the credentials.
README.md
Keep it short: one paragraph on what the module does, a usage example that actually works, and the inputs and outputs. Here's the one for this module:
# service-cert
Issues a TLS certificate for one internal service, signed by an existing CA,
and writes `<service_name>.crt` and `<service_name>.key` (mode 0600) to `output_dir`.
## Usage
```hcl
module "billing_cert" {
source = "./modules/service-cert"
service_name = "billing"
dns_names = ["billing.internal.acme.example", "billing"]
ca_cert_pem = module.ca.cert_pem
ca_private_key_pem = module.ca.private_key_pem
output_dir = "${path.root}/certs"
}
```
## Inputs
| Name | Type | Default | Description |
|---|---|---|---|
| service_name | string | n/a | Common name and file name prefix |
| dns_names | list(string) | n/a | Subject alternative names |
| ca_cert_pem | string | n/a | Signing CA certificate |
| ca_private_key_pem | string (sensitive) | n/a | Signing CA key |
| validity_days | number | 90 | Lifetime, 1-397 days |
| output_dir | string | n/a | Where the files are written |
## Outputs
`cert_path`, `key_path`, `expires_at`, `cert_pem`.Calling the module
Add billing.tf to the root module:
module "billing_cert" {
source = "./modules/service-cert"
service_name = "billing"
dns_names = ["billing.internal.acme.example", "billing"]
ca_cert_pem = tls_self_signed_cert.ca.cert_pem
ca_private_key_pem = tls_private_key.ca.private_key_pem
output_dir = "${path.root}/certs"
}path.root is the root module's directory. Inside a child module, path.module
would point at modules/service-cert, which is the wrong place for output files, so
the caller decides. Every new module block needs a terraform init before anything
else works:
terraform initInitializing the backend...
Initializing modules...
- billing_cert in modules/service-cert
Initializing provider plugins...
[…]For a local path there's nothing to download; init just records where the module lives. Now plan and apply:
terraform plan | grep -E '^ # |^Plan:' # module.billing_cert.local_file.cert will be created
# module.billing_cert.local_sensitive_file.key will be created
# module.billing_cert.tls_cert_request.this will be created
# module.billing_cert.tls_locally_signed_cert.this will be created
# module.billing_cert.tls_private_key.this will be created
Plan: 5 to add, 0 to change, 0 to destroy.terraform apply -auto-approve
openssl verify -CAfile certs/ca.crt certs/billing.crt
ls -l certs[…]
Apply complete! Resources: 5 added, 0 changed, 0 destroyed.
certs/billing.crt: OK
total 20
-rw-r--r-- 1 sid sid 749 Nov 9 21:56 api.crt
-rw------- 1 sid sid 227 Nov 9 21:56 api.key
-rw-r--r-- 1 sid sid 769 Nov 9 21:56 billing.crt
-rw------- 1 sid sid 227 Nov 9 21:56 billing.key
-rw-r--r-- 1 sid sid 704 Nov 9 21:56 ca.crtResources inside a module get addresses prefixed with the module path:
module.billing_cert.tls_private_key.this. That's what you'll see in state list,
in plans, and in any moved block that refers to them.
The validation rule earns its keep the first time someone passes a bad name. I set
service_name = "Billing_API" in billing.tf:
Error: Invalid value for variable
on billing.tf line 4, in module "billing_cert":
4: service_name = "Billing_API"
├────────────────
│ var.service_name is "Billing_API"
service_name must be 2-31 lowercase letters, digits or hyphens, starting with
a letter.
This was checked by the validation rule at
modules/service-cert/variables.tf:5,3-13.The error points at the caller's line, not at the module's internals, which is exactly where the person who made the mistake will look.
Calling a module many times with for_each
One module block per service is better than five resources per service, but it's
still a block per service. for_each works on module blocks just as it does on
resources. Replace billing.tf with services.tf:
variable "services" {
description = "Services that need a certificate, keyed by service name."
type = map(object({
dns_names = list(string)
validity_days = optional(number, 90)
}))
default = {
billing = { dns_names = ["billing.internal.acme.example", "billing"] }
ledger = { dns_names = ["ledger.internal.acme.example", "ledger"], validity_days = 30 }
}
}
module "service_cert" {
source = "./modules/service-cert"
for_each = var.services
service_name = each.key
dns_names = each.value.dns_names
validity_days = each.value.validity_days
ca_cert_pem = tls_self_signed_cert.ca.cert_pem
ca_private_key_pem = tls_private_key.ca.private_key_pem
output_dir = "${path.root}/certs"
}
moved {
from = module.billing_cert
to = module.service_cert["billing"]
}optional(number, 90) lets most entries skip validity_days while ledger asks for
30. The moved block is the important part: the billing certificate already exists
at module.billing_cert, and one moved block relocates the whole module instance,
every resource inside it, to its new key.
terraform init
terraform plan | grep -E '^ # |^Plan:' # module.billing_cert.local_file.cert has moved to module.service_cert["billing"].local_file.cert
# module.billing_cert.local_sensitive_file.key has moved to module.service_cert["billing"].local_sensitive_file.key
# module.billing_cert.tls_cert_request.this has moved to module.service_cert["billing"].tls_cert_request.this
# module.billing_cert.tls_locally_signed_cert.this has moved to module.service_cert["billing"].tls_locally_signed_cert.this
# module.billing_cert.tls_private_key.this has moved to module.service_cert["billing"].tls_private_key.this
# module.service_cert["ledger"].local_file.cert will be created
# module.service_cert["ledger"].local_sensitive_file.key will be created
# module.service_cert["ledger"].tls_cert_request.this will be created
# module.service_cert["ledger"].tls_locally_signed_cert.this will be created
# module.service_cert["ledger"].tls_private_key.this will be created
Plan: 5 to add, 0 to change, 0 to destroy.Billing moves, ledger is new. From now on, a new service is a one-line change to the
services map.
Prefer for_each with a map over count for modules. With count, the instances
are module.service_cert[0], [1] and so on, and removing the first service from a
list shifts every index after it, which replaces every certificate after it.
Module outputs
The only things that cross the module boundary outward are outputs, and they're
addressed as module.NAME.OUTPUT, or module.NAME["key"].OUTPUT with for_each.
Here's a root outputs.tf that summarizes every certificate:
output "certificates" {
description = "Certificate file and expiry time for each service."
value = {
for name, cert in module.service_cert : name => {
path = cert.cert_path
expires_at = cert.expires_at
}
}
}module.service_cert on its own is a map of objects, one per key, so a for
expression can walk it. After the apply:
terraform apply -auto-approve[…]
Apply complete! Resources: 5 added, 0 changed, 0 destroyed.
Outputs:
certificates = {
"billing" = {
"expires_at" = "2027-02-07T21:56:25.868585857-05:00"
"path" = "./certs/billing.crt"
}
"ledger" = {
"expires_at" = "2026-12-09T21:56:29.987140183-05:00"
"path" = "./certs/ledger.crt"
}
}The ledger certificate is good for 30 days, the billing one for 90. openssl
confirms what the module wrote:
openssl x509 -in certs/ledger.crt -noout -subject -issuer -enddate -ext subjectAltNamesubject=O = Acme Corp, CN = ledger
issuer=O = Acme Corp, CN = Acme Internal CA
notAfter=Dec 10 02:56:29 2026 GMT
X509v3 Subject Alternative Name:
DNS:ledger.internal.acme.example, DNS:ledgerComposition instead of nesting
The CA is still four loose resources in the root module. It's a natural second
module: modules/ca, with a cert_pem output and a sensitive private_key_pem
output. It's small enough that I kept variables, resources and outputs in one
main.tf:
variable "common_name" {
description = "Common name of the CA certificate."
type = string
}
variable "organization" {
description = "Organization in the CA certificate subject."
type = string
}
variable "validity_years" {
description = "CA certificate lifetime in years."
type = number
default = 5
}
variable "output_dir" {
description = "Directory to write ca.crt into."
type = string
}
resource "tls_private_key" "this" {
algorithm = "ECDSA"
ecdsa_curve = "P384"
}
resource "tls_self_signed_cert" "this" {
private_key_pem = tls_private_key.this.private_key_pem
is_ca_certificate = true
validity_period_hours = var.validity_years * 365 * 24
allowed_uses = ["cert_signing", "crl_signing"]
subject {
common_name = var.common_name
organization = var.organization
}
}
resource "local_file" "cert" {
filename = "${var.output_dir}/ca.crt"
content = tls_self_signed_cert.this.cert_pem
file_permission = "0644"
}
output "cert_pem" {
description = "The CA certificate, PEM-encoded."
value = tls_self_signed_cert.this.cert_pem
}
output "private_key_pem" {
description = "The CA private key, PEM-encoded."
value = tls_private_key.this.private_key_pem
sensitive = true
}The sensitive = true on private_key_pem isn't optional: Terraform refuses to
pass a sensitive value out through an output that isn't marked sensitive.
Now there's a design decision. The service-cert module needs a CA. It could create
one itself, or call the ca module from inside, so callers only ever deal with one
module. Don't. Each service would get its own CA, nothing could trust them all, and
the CA would be buried two levels deep where no one can reuse it. Instead, the root
module wires the two together. The root main.tf shrinks to this:
terraform {
required_version = ">= 1.5"
required_providers {
tls = { source = "hashicorp/tls", version = "~> 4.0" }
local = { source = "hashicorp/local", version = "~> 2.5" }
}
}
module "ca" {
source = "./modules/ca"
common_name = "Acme Internal CA"
organization = "Acme Corp"
output_dir = "${path.root}/certs"
}In services.tf, the CA inputs now come from the ca module's outputs, and the
services map gains the api service that used to be hand-written:
default = {
api = { dns_names = ["api.internal.acme.example", "api"] }
billing = { dns_names = ["billing.internal.acme.example", "billing"] }
ledger = { dns_names = ["ledger.internal.acme.example", "ledger"], validity_days = 30 }
} ca_cert_pem = module.ca.cert_pem
ca_private_key_pem = module.ca.private_key_pemThis is composition: small modules that each do one job, take their dependencies as inputs, and get connected by the root module. The rules of thumb I follow:
- Keep the module tree shallow. Root module plus one level of children covers most projects. A module that calls a module that calls a module is hard to read and harder to refactor.
- Pass dependencies in as variables (an ID, an ARN, a PEM) rather than creating or looking them up inside the module. The caller then decides whether the CA, the VPC or the DNS zone is shared, new, or comes from another project.
- A module should be worth its interface. A module wrapping one resource with every argument passed straight through adds indirection and no rules. Make a module when there's a group of resources that always travel together, or a policy (like "keys are always 0600") worth enforcing.
Refactoring existing resources into a module
There's a catch. The CA and the api certificate already exist in state under their
old flat addresses (tls_private_key.ca, tls_locally_signed_cert.api and so on).
Here's the plan after terraform init (to install the ca module), with no other
changes:
terraform plan | grep -E '^ # .*(must be replaced|will be created|will be destroyed)|^Plan:' # local_file.api_cert will be destroyed
# local_file.ca_cert will be destroyed
# local_sensitive_file.api_key will be destroyed
# tls_cert_request.api will be destroyed
# tls_locally_signed_cert.api will be destroyed
# tls_private_key.api will be destroyed
# tls_private_key.ca will be destroyed
# tls_self_signed_cert.ca will be destroyed
# module.ca.local_file.cert will be created
# module.ca.tls_private_key.this will be created
# module.ca.tls_self_signed_cert.this will be created
# module.service_cert["api"].local_file.cert will be created
# module.service_cert["api"].local_sensitive_file.key will be created
# module.service_cert["api"].tls_cert_request.this will be created
# module.service_cert["api"].tls_locally_signed_cert.this will be created
# module.service_cert["api"].tls_private_key.this will be created
# module.service_cert["billing"].local_file.cert must be replaced
# module.service_cert["billing"].tls_locally_signed_cert.this must be replaced
# module.service_cert["ledger"].local_file.cert must be replaced
# module.service_cert["ledger"].tls_locally_signed_cert.this must be replaced
Plan: 12 to add, 0 to change, 12 to destroy.Read that carefully, because it's worse than it first looks. Terraform would destroy the CA and create a new one, and because billing's and ledger's certificates are signed by the CA, they'd be reissued too. In a real deployment every service would suddenly present certificates its peers don't trust. All from a refactor that changed no behavior.
The fix is one moved block per resource, from the old flat address to the new
address inside the module. I put them in refactor.tf:
# refactor.tf: the CA and the api certificate moved into modules (November 2026).
moved {
from = tls_private_key.ca
to = module.ca.tls_private_key.this
}
moved {
from = tls_self_signed_cert.ca
to = module.ca.tls_self_signed_cert.this
}
moved {
from = local_file.ca_cert
to = module.ca.local_file.cert
}
moved {
from = tls_private_key.api
to = module.service_cert["api"].tls_private_key.this
}
moved {
from = tls_cert_request.api
to = module.service_cert["api"].tls_cert_request.this
}
moved {
from = tls_locally_signed_cert.api
to = module.service_cert["api"].tls_locally_signed_cert.this
}
moved {
from = local_file.api_cert
to = module.service_cert["api"].local_file.cert
}
moved {
from = local_sensitive_file.api_key
to = module.service_cert["api"].local_sensitive_file.key
}terraform plan | grep -E '^ # |^Plan:' # local_file.ca_cert has moved to module.ca.local_file.cert
# tls_private_key.ca has moved to module.ca.tls_private_key.this
# tls_self_signed_cert.ca has moved to module.ca.tls_self_signed_cert.this
# local_file.api_cert has moved to module.service_cert["api"].local_file.cert
# local_sensitive_file.api_key has moved to module.service_cert["api"].local_sensitive_file.key
# tls_cert_request.api has moved to module.service_cert["api"].tls_cert_request.this
# tls_locally_signed_cert.api has moved to module.service_cert["api"].tls_locally_signed_cert.this
# tls_private_key.api has moved to module.service_cert["api"].tls_private_key.this
Plan: 0 to add, 0 to change, 0 to destroy.Eight moves, nothing else. That 0 to add, 0 to change, 0 to destroy is the
acceptance test for any refactor: if the plan shows a single change you didn't intend,
a moved block is missing or the module's arguments don't exactly match the old
resource's. Here they match because I kept the same values: the module's default
validity_days = 90 equals the old 90 * 24 hours, and "${path.root}/certs"
produces the same file names as the old "${path.module}/certs".
terraform apply -auto-approve
for c in api billing ledger; do openssl verify -CAfile certs/ca.crt certs/$c.crt; done[…]
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
certs/api.crt: OK
certs/billing.crt: OK
certs/ledger.crt: OKThe final layout:
.
├── main.tf
├── modules
│ ├── ca
│ │ ├── main.tf
│ │ └── versions.tf
│ └── service-cert
│ ├── README.md
│ ├── main.tf
│ ├── outputs.tf
│ ├── variables.tf
│ └── versions.tf
├── outputs.tf
└── services.tfModule sources
source accepts several kinds of address. These are the ones you'll actually use:
| Source | Example | Versioning |
|---|---|---|
| Local path | "./modules/service-cert" | Same commit as the caller |
| Terraform Registry | "terraform-aws-modules/s3-bucket/aws" | version = "~> 5.17" argument |
| Git over HTTPS | "git::https://github.com/acme/modules.git//service-cert?ref=v1.4.0" | ?ref= tag, branch or commit |
| Git over SSH | "git::ssh://git@github.com/acme/modules.git//service-cert?ref=v1.4.0" | ?ref= |
| Private registry | "app.terraform.io/acme/service-cert/tls" | version argument |
Local paths must start with ./ or ../. A double slash (//service-cert) selects
a subdirectory inside a repository, and the version argument only works for
registry sources; for git you put the version in ?ref=.
A registry module with a version constraint
The public registry is full of well-maintained modules. terraform-aws-modules/s3-bucket
is one of the most widely used, and it bundles the dozen separate resources a
properly configured S3 bucket needs:
terraform {
required_version = ">= 1.7"
required_providers {
aws = { source = "hashicorp/aws", version = "~> 6.0" }
}
}
provider "aws" {
region = "eu-west-1"
}
module "invoices_bucket" {
source = "terraform-aws-modules/s3-bucket/aws"
version = "~> 5.17"
bucket = "acme-invoices-prod"
versioning = {
enabled = true
}
server_side_encryption_configuration = {
rule = {
apply_server_side_encryption_by_default = {
sse_algorithm = "aws:kms"
}
}
}
attach_deny_insecure_transport_policy = true
tags = {
Team = "payments"
Environment = "prod"
}
}
output "invoices_bucket_arn" {
value = module.invoices_bucket.s3_bucket_arn
}terraform initInitializing the backend...
Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/s3-bucket/aws 5.17.0 for invoices_bucket...
- invoices_bucket in .terraform/modules/invoices_bucket
- invoices_bucket.s3_file_system in .terraform/modules/invoices_bucket/modules/file-system
Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 6.0, >= 6.44.0"...
- Installing hashicorp/aws v6.72.0...
- Installed hashicorp/aws v6.72.0 (signed by HashiCorp)
[…]Three things to notice. ~> 5.17 picked 5.17.0, the newest release that allows.
The module brought its own nested module along. And the provider constraint became
~> 6.0, >= 6.44.0: the module's own versions.tf declares a minimum, exactly as
ours does, and Terraform combined the two.
Where did everything go? .terraform/modules/modules.json records it:
jq -c '.Modules[] | {Key, Source, Version}' .terraform/modules/modules.json{"Key":"","Source":"","Version":null}
{"Key":"invoices_bucket","Source":"registry.terraform.io/terraform-aws-modules/s3-bucket/aws","Version":"5.17.0"}
{"Key":"invoices_bucket.s3_file_system","Source":"./modules/file-system","Version":null}Unlike providers, module versions aren't recorded in .terraform.lock.hcl. A
~> 5.17 constraint will pick up 5.18 on a fresh terraform init or after
terraform init -upgrade. If you need byte-for-byte reproducibility, pin the exact
version (version = "5.17.0") and upgrade on purpose.
A git source pinned to a tag
The same module straight from its git repository, pinned to the tag:
module "invoices_bucket" {
source = "git::https://github.com/terraform-aws-modules/terraform-aws-s3-bucket.git?ref=v5.17.0"
bucket = "acme-invoices-prod"
}terraform initInitializing the backend...
Initializing modules...
Downloading git::https://github.com/terraform-aws-modules/terraform-aws-s3-bucket.git?ref=v5.17.0 for invoices_bucket...
- invoices_bucket in .terraform/modules/invoices_bucket
- invoices_bucket.s3_file_system in .terraform/modules/invoices_bucket/modules/file-system
[…]Git sources are how most companies share private modules without running a registry.
Always pin ?ref= to a tag. Without it you get whatever the default branch looks like
at the moment of each init, and two engineers can deploy different module code from
the same commit.
Testing a registry module offline
Before you adopt someone else's module, you want to know what it builds. I ran
terraform validate on the invoices configuration, which passed, and then tried a
plan with dummy AWS credentials and the same offline_override.tf trick from the
state tutorial:
terraform plan[…]
Plan: 4 to add, 0 to change, 0 to destroy.
Changes to Outputs:
+ invoices_bucket_arn = (known after apply)
Error: reading STS Caller Identity
with module.invoices_bucket.data.aws_caller_identity.current[0],
on .terraform/modules/invoices_bucket/main.tf line 11, in data "aws_caller_identity" "current":
11: data "aws_caller_identity" "current" {
operation error STS: GetCallerIdentity, https response error StatusCode: 403,
RequestID: 62a9d38a-45b7-41ec-8877-5b00850e6bfa, api error
InvalidClientTokenId: The security token included in the request is invalid.The module reads data sources (the account ID, the partition, the region), and data
sources call AWS even during a plan. That's normal for registry modules, and it's
what Terraform's test framework and mock_provider solve: a mocked provider answers
every call with made-up values, fully offline. Put this in
tests/invoices_bucket.tftest.hcl:
mock_provider "aws" {
# Mocked data sources return random strings. The module feeds policy
# documents into other policy documents, and the provider validates those
# as JSON, so give the mock a valid (empty) policy.
mock_data "aws_iam_policy_document" {
defaults = {
json = "{\"Version\":\"2012-10-17\",\"Statement\":[]}"
}
}
}
run "bucket_is_versioned_and_tagged" {
command = plan
assert {
condition = module.invoices_bucket.aws_s3_bucket_versioning_status == "Enabled"
error_message = "Versioning must be enabled on the invoices bucket."
}
assert {
condition = module.invoices_bucket.s3_bucket_tags["Team"] == "payments"
error_message = "The bucket must be tagged with its owning team."
}
}
run "apply_with_mocks" {
assert {
condition = output.invoices_bucket_arn != null
error_message = "The module should expose the bucket ARN."
}
}terraform testtests/invoices_bucket.tftest.hcl... in progress
run "bucket_is_versioned_and_tagged"... pass
run "apply_with_mocks"... pass
tests/invoices_bucket.tftest.hcl... tearing down
tests/invoices_bucket.tftest.hcl... pass
Success! 2 passed, 0 failed.The mock_data block is there because my first attempt, with a bare
mock_provider "aws" {}, failed. That error is in
Common mistakes. The second run block has no command, so it
defaults to apply: Terraform "creates" everything against the mock, and computed
values like the ARN get made-up values. In the verbose output
(terraform test -verbose) the ARN was:
invoices_bucket_arn = "396ebti9"So assertions about the shape of mocked values are pointless with a bare mock.
The Testing and CI tutorial shows
override_resource for pinning specific values, and goes much deeper into the test
framework.
Where you'll use this
- A platform team's module library. The pattern above scales directly: a
modules/directory (or a separate repository with git tags) holding the company's opinionated building blocks, such as a service certificate, a bucket with the security team's defaults, or a standard alarm set. Product teams consume them with a few lines each. The validation rules and fixed settings inside the modules are your policy, enforced at plan time. - Per-tenant or per-service stamping. Anything you create once per customer,
service or region becomes a module plus a map and
for_each. Onboarding is a one-line pull request, like adding a service toserviceshere. - Environments. The same modules called from a
dev,stagingandprodroot module with different inputs is the backbone of the next tutorial, Managing Multiple Environments. - Wrapping registry modules. When a public module does 95% of what you need, a thin local module that calls it with your company's fixed settings (encryption on, public access blocked, required tags) gives teams a smaller interface and keeps the policy in one place.
- The capstone. A Static Website on AWS builds a complete module with S3, CloudFront and optional DNS, then calls it from two environments.
Common mistakes
Forgetting terraform init after adding a module
terraform planError: Module not installed
on billing.tf line 1:
1: module "billing_cert" {
This module is not yet installed. Run "terraform init" to install all modules
required by this configuration.Any new module block, and any change to a source or version, needs
terraform init. Upgrading a registry module within its constraint needs
terraform init -upgrade. It's always safe to re-run.
A version constraint nothing satisfies
Typing version = "~> 9.0" for the S3 module:
Error: Unresolvable module version constraint
on main.tf line 13:
13: module "invoices_bucket" {
There is no available version of module
"registry.terraform.io/terraform-aws-modules/s3-bucket/aws" (main.tf:13)
which matches the given version constraint. The newest available version is
5.17.0.The message tells you the newest version that exists. Check the module's changelog before you jump a major version: major versions of popular modules regularly rename variables and move resources.
Wrapping existing resources in a module without moved blocks
That's the 12 to add, 12 to destroy plan from the refactoring section. Any change
of address (into a module, between modules, from count to for_each) needs moved
blocks, and the plan must show only moves before you apply.
Mocked data that the provider can't accept
My first test run of the S3 module, with a bare mock_provider "aws" {}:
run "bucket_is_versioned_and_tagged"... fail
Error: "source_policy_documents.0" contains an invalid JSON: invalid character 'a' looking for beginning of value
with module.invoices_bucket.data.aws_iam_policy_document.combined[0],
on .terraform/modules/invoices_bucket/main.tf line 754, in data "aws_iam_policy_document" "combined":
754: source_policy_documents = compact([
[…]A mock provider fills computed attributes with random strings, but the real
provider's argument validation still runs. The module passes one mocked policy
document's json into another's source_policy_documents, which must be valid JSON.
The fix is a mock_data block with a valid default, as in the test file above.
Summary
- A module is a directory of
.tffiles. The root module calls child modules withmoduleblocks; variables go in, outputs come out, and nothing else crosses the boundary. - Lay modules out as
variables.tf,main.tf,outputs.tf,versions.tfand aREADME.md. Validate inputs inside the module so callers get clear plan-time errors. - Modules declare minimum provider versions (
>=) and never configure providers; the root module pins versions and owns provider blocks. for_eachon a module block stamps out one instance per map key. Use maps, notcount, so removing one entry doesn't shift the others.- Compose small modules in the root module and pass dependencies in as inputs. Avoid deep nesting.
- Moving existing resources into a module needs a
movedblock per resource (or one per module instance). The plan must say0 to add, 0 to change, 0 to destroy. - Sources: local paths for in-repo modules, the registry with a
versionconstraint, git with?ref=pinned to a tag. Module versions are not in the lock file. - Registry modules often read data sources, so offline plans fail.
terraform testwithmock_providerexercises them without credentials.
Exercises
Exercises 1 to 4 build on the pki project in its final state.
The search team needs a certificate for search.internal.acme.example and search,
valid for 14 days. Add it, check how many resources the plan creates, apply, and
confirm the expiry date with openssl.
Show Solution
Add one line to the services map in services.tf:
search = { dns_names = ["search.internal.acme.example", "search"], validity_days = 14 }terraform plan | grep -E '^Plan:'
terraform apply -auto-approve | grep -E 'Apply complete'
openssl x509 -in certs/search.crt -noout -subject -enddatePlan: 5 to add, 0 to change, 0 to destroy.
Apply complete! Resources: 5 added, 0 changed, 0 destroyed.
subject=O = Acme Corp, CN = search
notAfter=Nov 24 02:58:04 2026 GMTFive resources, one module instance, and no change to anything that already exists.
That's the payoff of for_each over a map.
Someone has to remember to rotate the CA before it expires. Add an expires_at
output to the ca module, and a root output ca_expires_at that passes it through.
Print it with terraform output -raw.
Show Solution
Append to modules/ca/main.tf:
output "expires_at" {
description = "RFC 3339 timestamp when the CA certificate expires."
value = tls_self_signed_cert.this.validity_end_time
}And to the root outputs.tf:
output "ca_expires_at" {
description = "When the internal CA expires. Plan the rotation well before this."
value = module.ca.expires_at
}terraform apply -auto-approve | grep -E 'Apply complete|ca_expires_at'
terraform output -raw ca_expires_at; echo + ca_expires_at = "2031-11-08T21:56:22.798533293-05:00"
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
ca_expires_at = "2031-11-08T21:56:22.798533293-05:00"
2031-11-08T21:56:22.798533293-05:00A value inside a child module is invisible to the root until the child outputs it, and invisible outside Terraform until the root outputs it. Adding outputs never changes infrastructure, which is why the apply reports zero changes.
Make the service-cert module reject an empty dns_names list or any name with
uppercase letters. Prove it with
-var 'services={"search" = {dns_names = ["Search.internal.acme.example"]}}', then
confirm the normal configuration still plans with no changes.
Hint
alltrue() over a for expression checks every element of a list.
Show Solution
In modules/service-cert/variables.tf:
variable "dns_names" {
description = "DNS names the certificate is valid for."
type = list(string)
validation {
condition = length(var.dns_names) > 0 && alltrue([for n in var.dns_names : n == lower(n)])
error_message = "dns_names must contain at least one name, all lowercase."
}
}terraform plan -var 'services={"search" = {dns_names = ["Search.internal.acme.example"]}}'[…]
Error: Invalid value for variable
on services.tf line 20, in module "service_cert":
20: dns_names = each.value.dns_names
├────────────────
│ var.dns_names is list of string with 1 element
dns_names must contain at least one name, all lowercase.
This was checked by the validation rule at
modules/service-cert/variables.tf:15,3-13.terraform plan | grep -E 'No changes|Plan:'No changes. Your infrastructure matches the configuration.DNS names are case-insensitive, but certificate tooling and humans comparing strings aren't, so normalizing at the module boundary saves a confusing mismatch later.
You decide this is a poor name and want tls_private_key.service,
tls_cert_request.service and tls_locally_signed_cert.service inside
service-cert. Make the rename so that every existing caller, for every service, gets
a plan with nothing to add or destroy, and without touching any root module file.
Hint
moved blocks can live inside the module itself, using addresses relative to the
module.
Show Solution
Rename the three resources and their references in main.tf and outputs.tf, then
add modules/service-cert/moved.tf:
# v1.1: resources renamed from "this" to "service".
moved {
from = tls_private_key.this
to = tls_private_key.service
}
moved {
from = tls_cert_request.this
to = tls_cert_request.service
}
moved {
from = tls_locally_signed_cert.this
to = tls_locally_signed_cert.service
}terraform plan | grep -E 'has moved' | head -4
terraform plan | grep -c 'has moved'
terraform plan | grep -E '^Plan:' # module.service_cert["api"].tls_cert_request.this has moved to module.service_cert["api"].tls_cert_request.service
# module.service_cert["api"].tls_locally_signed_cert.this has moved to module.service_cert["api"].tls_locally_signed_cert.service
# module.service_cert["api"].tls_private_key.this has moved to module.service_cert["api"].tls_private_key.service
# module.service_cert["billing"].tls_cert_request.this has moved to module.service_cert["billing"].tls_cert_request.service
12
Plan: 0 to add, 0 to change, 0 to destroy.Three moved blocks produced twelve moves: three resources in each of four module
instances. Because the blocks ship inside the module, every caller gets the rename
for free on their next plan. This is why published modules keep their moved blocks
indefinitely. It also chains correctly with the root's refactor.tf, whose to
addresses still say this: Terraform follows tls_private_key.api to
...tls_private_key.this to ...tls_private_key.service.
Tested with: Terraform v1.17.1 on Ubuntu 24.04 (WSL2, linux_amd64), with
hashicorp/tls v4.4.2, hashicorp/local v2.9.1, hashicorp/aws v6.72.0 and
terraform-aws-modules/s3-bucket 5.17.0, OpenSSL 3.0.13, November 2026. The
certificate authority project was applied for real at every step, and openssl
verified the chain after each refactor. The S3 module was downloaded from the
registry and from GitHub, validated, and tested with terraform test against a
mocked AWS provider; the plan with dummy credentials failed at the STS call as shown,
and nothing was applied to a real AWS account. Commands ran with -no-color.
Written by The Dark Debugger
Engineer documenting the things that took me too long to learn, so they take you less time. Every Terraform tutorial here is tested end to end before publishing.