Terraform modules
Package a secure S3 bucket as a reusable Terraform module with validated inputs, outputs and a terraform test suite, version it with Git tags, call it from registry and Git sources, and decide when a module is worth writing at all.
Assumes: Terraform 1.17.2 · Terraform AWS provider 6.73.0 (>= 6.0, < 7.0) · .NET 10 LTS · Amazon.CDK.Lib 2.277.0 · Region us-east-1. Verified against official sources on 2026-11-18.
Learning objectives
By the end of this lesson you can:
- Explain the difference between a root module and a child module, and how inputs, outputs and providers cross the boundary.
- Write a module with typed, validated variables, sensible secure defaults and outputs that expose only what callers need.
- Call a module from a local path, the Terraform Registry and a Git tag, and pin versions so a change is always a deliberate pull request.
- Call one module many times with
for_each, and rename or move resources inside a module without destroying them usingmovedblocks. - Write a
terraform testsuite that runs with no AWS account by using a mock provider. - Decide when a module is the right abstraction and when it is just a thin wrapper that adds cost and confusion.
- Map the idea onto a CDK (C#) L3 construct so you can explain both to a team.
Prerequisites
- Terraform fundamentals: HCL, variables, outputs, plan and apply.
- Terraform state: why moving a resource address matters to state.
- Tools: Docker Desktop (the
tfPowerShell function from the fundamentals lesson). No AWS account is needed for the main exercise; the optional deploy uses thelearn-sandboxSSO profile.
Why this matters in banking
Harbourline has forty teams. Each one needs S3 buckets, and every bucket must be encrypted with a customer managed key, versioned, blocked from public access, and must refuse plain HTTP. If each team copies a snippet from the wiki, you will have forty slightly different snippets within a quarter. One has a typo in the TLS-only policy. Another forgot the public access block. The auditor samples three buckets and finds two different configurations.
A module fixes this by moving the decision into one reviewed place. The security team owns secure-bucket; application teams call it with three or four inputs. When a control changes (for example, lifecycle rules for noncurrent versions), one pull request changes it everywhere, one environment at a time, on a schedule each team controls by bumping a version number.
The flip side matters just as much. A bad module is worse than no module: a wrapper with thirty variables that mirrors every argument of the underlying resource, owned by nobody, used by everybody. This lesson shows how to write the good kind and how to recognise the bad kind.
The idea in plain language
A module is a folder of Terraform files. That is all. Every Terraform configuration is already a module: the folder where you run terraform plan is the root module. A child module is another folder that the root (or another module) calls with a module block.
A module has three interfaces:
- Inputs:
variableblocks. The caller sets them in themoduleblock. - Outputs:
outputblocks. The caller reads them asmodule.<name>.<output>. - Providers: a child module inherits the root's provider configuration by default. It declares which providers it needs with
required_providers, but it does not (normally) configure them.
Everything else is private. A resource inside a module is not visible to the caller unless you output it.
Analogy: a module is a standard branch fit-out kit. The bank's property team does not let each branch choose its own door locks and alarm panels. The kit has a short order form (the variables: how many counters, which colour), and what arrives is always the approved lock, the approved alarm and the approved safe. You cannot order a kit without a safe, and you cannot see inside the safe's mechanism, only the key number it gives you (the outputs).
What problem modules solve
| Problem | How a module helps |
|---|---|
| Copy-paste drift between teams | One source of truth, referenced by version |
| Security controls that depend on remembering | Controls are defaults inside the module; opting out needs a visible, reviewable variable |
| Long root configurations nobody can read | A root file of ten module blocks reads like an architecture diagram |
| Repeating a pattern per environment or per tenant | for_each or count on the module block |
| Safe rollout of a control change | New module version, promoted dev to test to prod |
Honest limitations:
- A module is an interface you now have to keep stable. Renaming a variable is a breaking change for every caller.
- Modules hide resources. A reviewer reading only the root plan still sees the full resource list, but a reader of the
.tffiles sees only themoduleblock and must open the module to know what is created. - Modules cannot loop over providers or Regions dynamically; each provider configuration must be passed in explicitly.
terraform testis good for checking logic and defaults but is not a substitute for deploying once to a real sandbox account.
Microsoft / Azure comparison
| You know (Microsoft/Azure) | Terraform / AWS equivalent | What's different |
|---|---|---|
Bicep modules (module x 'x.bicep') | Terraform module blocks | Bicep modules are compiled into one ARM deployment; Terraform modules are folded into one plan and one state |
| Azure Verified Modules | Terraform Registry modules (for example terraform-aws-modules) and your own internal modules | Registry modules are community- or vendor-maintained; read the code before you trust them in a bank |
| Template specs (versioned ARM templates) | Module versions via Git tags or a private registry | You pin a version in the caller, not in a central store the caller does not see |
| NuGet package with version ranges | Module version constraint such as ~> 2.1 | Same semantic-versioning idea; registry and Git sources are resolved at terraform init |
| A shared class library of helper methods | A child module | Both hide implementation behind a small public surface |
| xUnit tests for the library | terraform test with mock_provider | Tests are HCL files, not C# |
Architecture
Security-boundary view. The module is where you enforce guard-rails. The caller can supply a key ARN and a name; the caller cannot switch off the public access block unless the module deliberately offers that variable, and offering it would be a decision a reviewer sees.
Step-by-step implementation
You will build a secure-bucket module, call it twice from a root configuration, test it with no AWS account, rename a resource safely, and publish a version.
Create the folder layout
m10-l10/
main.tf # root: calls the module
variables.tf
outputs.tf
versions.tf
modules/
secure-bucket/
main.tf
variables.tf
outputs.tf
versions.tf
README.md
tests/
secure_bucket.tftest.hclKeep README.md, versions.tf, variables.tf, outputs.tf and main.tf in every module. A reader should know where to look without opening each file.
Write the module's inputs
Decide the smallest interface that lets callers do their job. Everything secure is a default or a fixed behaviour; only genuine differences between teams become variables. The full file is in the Complete code section.
Write the module's resources
Eight small resources, each corresponding to one control a bank auditor asks about: ownership controls, public access block, versioning, SSE-KMS encryption with bucket key, lifecycle, and a bucket policy that denies non-TLS requests.
Call the module from the root
Use a local path while developing. Use for_each over a map so adding a team's bucket is a one-line change that shows as one reviewed + module.buckets["payments"] block in the plan.
Test without a cloud account
Run terraform test in the module folder. The mock provider answers every AWS call with fake data, so the test checks your logic and defaults in seconds.
Rename safely with a moved block
You will rename aws_s3_bucket.main to aws_s3_bucket.this and see that the plan shows a move, not a destroy and create.
Version it
Tag the module repository (v1.0.0) and change the caller to reference the tag. Later changes become v1.1.0 (compatible) or v2.0.0 (breaking).
AWS Console instructions
Modules are a Terraform concept, so the console has nothing to say about them. You use it only to confirm what a deployed module created, if you run the optional deploy:
- Console → S3 → Buckets and open the
hl-m10-l10-...bucket. - Properties tab: Bucket Versioning is Enabled; Default encryption is SSE-KMS and Bucket Key is Enabled.
- Permissions tab: Block public access shows all four settings On, and the bucket policy has the
DenyInsecureTransportstatement. - Management tab: a lifecycle rule for noncurrent versions.
AWS CLI
# Run the module tests with no AWS credentials at all (mock provider).
# In PowerShell with the `tf` function from the fundamentals lesson, run from modules/secure-bucket:
# tf init
# tf test
# Optional: after a real apply, confirm the controls the module promised.
# Bucket versioning status (expect "Enabled")
aws s3api get-bucket-versioning --bucket hl-m10-l10-audit-111122223333 --profile learn-sandbox
# Default encryption (expect aws:kms and BucketKeyEnabled true)
aws s3api get-bucket-encryption --bucket hl-m10-l10-audit-111122223333 --profile learn-sandbox
# Public access block (expect four true values)
aws s3api get-public-access-block --bucket hl-m10-l10-audit-111122223333 --profile learn-sandboxReplace 111122223333 with your account ID.
Infrastructure as Code
The same idea, packaged two ways. The Terraform module is a folder; the CDK equivalent is an L3 construct, a class that composes several L2 constructs behind a small interface.
module "buckets" {
source = "./modules/secure-bucket"
for_each = local.buckets
name = "hl-m10-l10-${each.key}-${local.account_id}"
kms_key_arn = aws_kms_key.data.arn
tags = { DataClass = each.value.data_class }
}Both hide eight controls behind two or three inputs. The difference is distribution: a Terraform module is consumed by a source and version in HCL; a construct is consumed as a NuGet package and a using statement.
Complete code
The root configuration and the module. Everything runs locally with terraform init and terraform test; the optional apply creates two small buckets and a key.
terraform {
required_version = ">= 1.10.0, < 2.0.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = ">= 6.0, < 7.0" # a module states a RANGE; the root's lock file pins the exact build
}
}
}variable "name" {
description = "Globally unique bucket name. Lowercase letters, digits and hyphens, 3 to 63 characters."
type = string
validation {
condition = can(regex("^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$", var.name))
error_message = "name must be 3-63 characters: lowercase letters, digits and hyphens, starting and ending with a letter or digit."
}
}
variable "kms_key_arn" {
description = "ARN of a customer managed KMS key for SSE-KMS. Null uses the AWS managed key aws/s3 (acceptable for dev only)."
type = string
default = null
}
variable "noncurrent_days" {
description = "Days to keep noncurrent object versions before they expire."
type = number
default = 90
validation {
condition = var.noncurrent_days >= 1 && var.noncurrent_days <= 3650
error_message = "noncurrent_days must be between 1 and 3650."
}
}
variable "force_destroy" {
description = "Allow terraform destroy to delete a bucket that still contains objects. Keep false outside throwaway labs."
type = bool
default = false
}
variable "tags" {
description = "Extra tags merged onto the bucket. Provider default_tags still apply."
type = map(string)
default = {}
}resource "aws_s3_bucket" "this" {
bucket = var.name
force_destroy = var.force_destroy
tags = var.tags
}
# Rename from an earlier version of this module (aws_s3_bucket.main): keeps the real bucket, changes only the address.
moved {
from = aws_s3_bucket.main
to = aws_s3_bucket.this
}
resource "aws_s3_bucket_ownership_controls" "this" {
bucket = aws_s3_bucket.this.id
rule {
object_ownership = "BucketOwnerEnforced" # ACLs disabled
}
}
resource "aws_s3_bucket_public_access_block" "this" {
bucket = aws_s3_bucket.this.id
block_public_acls = true
block_public_policy = true
ignore_public_acls = true
restrict_public_buckets = true
}
resource "aws_s3_bucket_versioning" "this" {
bucket = aws_s3_bucket.this.id
versioning_configuration {
status = "Enabled"
}
}
resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
bucket = aws_s3_bucket.this.id
rule {
bucket_key_enabled = true # fewer KMS requests, lower cost
apply_server_side_encryption_by_default {
sse_algorithm = "aws:kms"
kms_master_key_id = var.kms_key_arn # null = AWS managed key aws/s3
}
}
}
resource "aws_s3_bucket_lifecycle_configuration" "this" {
bucket = aws_s3_bucket.this.id
rule {
id = "expire-noncurrent-versions"
status = "Enabled"
filter {}
noncurrent_version_expiration {
noncurrent_days = var.noncurrent_days
}
abort_incomplete_multipart_upload {
days_after_initiation = 7
}
}
depends_on = [aws_s3_bucket_versioning.this] # lifecycle on noncurrent versions needs versioning first
}
data "aws_iam_policy_document" "tls_only" {
statement {
sid = "DenyInsecureTransport"
effect = "Deny"
actions = ["s3:*"]
resources = [aws_s3_bucket.this.arn, "${aws_s3_bucket.this.arn}/*"]
principals {
type = "*"
identifiers = ["*"]
}
condition {
test = "Bool"
variable = "aws:SecureTransport"
values = ["false"]
}
}
}
resource "aws_s3_bucket_policy" "this" {
bucket = aws_s3_bucket.this.id
policy = data.aws_iam_policy_document.tls_only.json
depends_on = [aws_s3_bucket_public_access_block.this] # avoids a known race between the two bucket-level settings
}output "bucket_id" {
description = "Bucket name."
value = aws_s3_bucket.this.id
}
output "bucket_arn" {
description = "Bucket ARN, for IAM policies."
value = aws_s3_bucket.this.arn
}# Runs with no AWS account: every provider call is answered by the mock.
mock_provider "aws" {}
variables {
name = "hl-test-audit-111122223333"
}
run "secure_defaults" {
command = plan
assert {
condition = aws_s3_bucket_versioning.this.versioning_configuration[0].status == "Enabled"
error_message = "Versioning must be enabled by default."
}
assert {
condition = alltrue([
aws_s3_bucket_public_access_block.this.block_public_acls,
aws_s3_bucket_public_access_block.this.block_public_policy,
aws_s3_bucket_public_access_block.this.ignore_public_acls,
aws_s3_bucket_public_access_block.this.restrict_public_buckets,
])
error_message = "All four public access block settings must be true."
}
assert {
condition = one(aws_s3_bucket_server_side_encryption_configuration.this.rule).apply_server_side_encryption_by_default[0].sse_algorithm == "aws:kms"
error_message = "Objects must be encrypted with SSE-KMS."
}
}
run "customer_key_is_used" {
command = plan
variables {
kms_key_arn = "arn:aws:kms:us-east-1:111122223333:key/11111111-2222-3333-4444-555555555555"
}
assert {
condition = one(aws_s3_bucket_server_side_encryption_configuration.this.rule).apply_server_side_encryption_by_default[0].kms_master_key_id == var.kms_key_arn
error_message = "The supplied customer managed key must be used."
}
}
run "bad_name_is_rejected" {
command = plan
variables {
name = "Not_A_Valid_Bucket_Name"
}
expect_failures = [var.name]
}
run "zero_retention_is_rejected" {
command = plan
variables {
noncurrent_days = 0
}
expect_failures = [var.noncurrent_days]
}terraform {
required_version = ">= 1.10.0, < 2.0.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.73"
}
}
}
provider "aws" {
region = var.region
default_tags {
tags = {
Project = "cea-lab"
Lab = "m10-l10"
Environment = "learn"
Owner = var.owner
}
}
}variable "region" {
type = string
default = "us-east-1"
}
variable "owner" {
description = "Value of the Owner tag."
type = string
}data "aws_caller_identity" "current" {}
locals {
account_id = data.aws_caller_identity.current.account_id
# One entry per bucket. Adding a bucket is a one-line change that shows up as one block in the plan.
buckets = {
audit = { data_class = "confidential" }
exports = { data_class = "internal" }
}
}
resource "aws_kms_key" "data" {
description = "Lesson 10 lab key for the secure-bucket module."
enable_key_rotation = true
deletion_window_in_days = 7
}
module "buckets" {
source = "./modules/secure-bucket"
for_each = local.buckets
name = "hl-m10-l10-${each.key}-${local.account_id}"
kms_key_arn = aws_kms_key.data.arn
force_destroy = true # learning shortcut: lets destroy succeed in the lab
tags = { DataClass = each.value.data_class }
}output "bucket_arns" {
description = "Bucket ARNs by logical name."
value = { for name, m in module.buckets : name => m.bucket_arn }
}Code explained line by line
required_providerswith>= 6.0, < 7.0in the module, and~> 6.73in the root. A module states the range it has been tested against; the root decides the exact version, and.terraform.lock.hclrecords the checksum. Putting an exact pin in a module makes it impossible to combine with other modules.validationblocks run at plan time, before any API call. A bad bucket name fails in two seconds on the laptop, not after an apply has created half the resources.kms_key_arndefaults tonull, so the encryption block passes nothing and S3 uses the AWS managed key. That is a deliberate default for dev. A pipeline policy (next lessons) can require a non-null key in production.- The
movedblock records that an earlier module version called the bucketaws_s3_bucket.main. Anyone upgrading finds Terraform renames the state entry instead of destroying a bucket full of data. Keepmovedblocks for at least a couple of releases. depends_onon the lifecycle rule and the bucket policy encodes two real ordering constraints that Terraform cannot infer from references.mock_provider "aws" {}replaces the real provider in tests.command = planmeans the test never needs apply.expect_failures = [var.name]passes only if the validation fails, which proves the guard-rail works.for_each = local.bucketscreates one module instance per key.module.buckets["audit"]andmodule.buckets["exports"]are separate addresses in state.- The output
{ for name, m in module.buckets : name => m.bucket_arn }turns the instances into a map keyed by logical name.
Sources, versions and when to use each
| Source | Example source | Version control | Use when |
|---|---|---|---|
| Local path | ./modules/secure-bucket | Same commit as the caller | Developing, or a module used only inside one repository |
| Git tag | git::https://example.com/harbourline/terraform-modules.git//secure-bucket?ref=v1.2.0 | Tag or commit SHA in ref | Internal modules shared across repositories; works with any Git host |
| Public registry | terraform-aws-modules/s3-bucket/aws with version = "~> 5.0" ⚠ VERIFY the current major version | version constraint | Well-known community modules after you have reviewed the code |
| Private registry | HCP Terraform or another private registry | version constraint | Larger organisations that want discovery and semantic-versioning enforcement |
Two rules for banks:
- Always pin.
?ref=mainor an unversioned registry source means a change you did not review can reach production. Use a tag, and for the highest assurance a commit SHA. - Read before you trust. A registry module runs with your credentials and can create IAM roles. Treat it like any third-party dependency: review, pin, and scan it in CI (see Policy-as-code and secure deployment).
Version constraint operators you will see: = 1.2.0 (exact), >= 1.2.0, < 2.0.0 (range) and ~> 1.2 (any 1.x from 1.2 upwards, never 2.0). ~> 1.2.3 allows only patch releases 1.2.x.
When NOT to write a module
A module earns its place when it encodes a decision that several callers must share. It does not when it only renames arguments.
| Smells like a bad module | Why | Better |
|---|---|---|
| Wraps one resource and exposes every argument as a variable | You have invented a second, worse, undocumented provider schema | Use the resource directly |
| Has a variable for every attribute "in case someone needs it" | Interface larger than the implementation | Start small; add a variable when a second caller needs it |
| Has one caller | No reuse yet | Keep it inline; extract when the second caller appears |
Contains count/for_each tangled with conditional resources via many booleans | Impossible to reason about | Split into two modules or use composition |
| Nobody owns it | Rots; breaking changes arrive unannounced | Give it a CODEOWNERS entry and a changelog |
A good module hides complexity (eight resources that must stay consistent) and exposes intent (name, key, retention).
Composition over configuration
Prefer many small modules composed in the root over one giant module with a mode switch. secure-bucket does not create a KMS key; the caller does, and passes the ARN. That keeps the module testable (no IAM or KMS dependency) and lets a team share one key across several buckets. Likewise the module does not create a replication role: replication would be a separate, optional module.
The last guideline is about providers. A module should not contain provider blocks (except configuration_aliases declarations in required_providers, when it truly needs two). Passing providers explicitly with providers = { aws = aws.eu } in the module block is the right way to place a module's resources in another Region or account.
Security considerations
⚠ Learning shortcut — not for production
The lab sets force_destroy = true and allows a null key so you can tear everything down quickly and test without creating a key policy. In production keep force_destroy = false, require a customer managed key for confidential buckets, and add S3 server access logging or CloudTrail data events to a separate log bucket (cdk-nag flags the missing log bucket as AwsSolutions-S1 for the same reason).
- Modules run with the caller's credentials. A module can create an IAM role with administrator rights. Review every module version before bumping it, as you would a NuGet package that runs at build time.
- Never put secrets in module variables. Values passed as variables end up in plan output and state. Mark genuinely sensitive inputs with
sensitive = trueand fetch secrets at run time from Secrets Manager. - Defaults are policy. If a variable is optional and its default is insecure, most callers will leave it. Make the secure behaviour the default, and the insecure choice an explicit, reviewable argument.
- Do not publish a module that hard-codes account IDs, ARNs or Regions. Use
data "aws_caller_identity"and variables. - Compliance note. A module that enforces encryption supports your control evidence; it does not make you compliant with PCI DSS or UK GDPR. Your compliance team still decides which controls apply.
Banking use case
Harbourline's cloud platform team maintains four internal modules in one repository: secure-bucket, private-queue (SQS with a dead-letter queue and encryption), service-role (an IAM role with a permissions boundary) and alarm-set (a standard set of CloudWatch alarms). Application teams compose them in their own repositories. A quarterly release train publishes v1.x versions; a change that would modify existing resources is v2.0.0 and needs a migration note. Each team's pipeline runs terraform plan on the bumped version in dev first, and the plan output is attached to the change ticket.
Common mistakes
- Pinning nothing.
source = "git::...secure-bucket"with noreftakes the default branch. A well-meaning merge intomainalters production on the next apply. - Renaming a resource inside a module without a
movedblock. Terraform plans destroy and create. For a bucket with data, that is an incident. Always check the plan for-/+. - Passing a whole object as one variable "for flexibility". You lose validation and documentation. Prefer separate typed variables, or an
object({...})with explicit attributes andoptional()defaults. - Outputting everything. Every output is a public contract. Output what callers need (IDs and ARNs) and nothing more.
- Testing only the happy path. Use
expect_failuresfor validations, otherwise a loosened regex goes unnoticed. - Adding
providerblocks inside a module. This blocksfor_eachandcounton the module and confuses removal. Receive providers from the caller.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Module not installed | You added a module block but did not run terraform init | Run terraform init (or init -upgrade after changing a version) |
Unsupported argument on a module call | The variable does not exist in the module version you pinned | Check the module's variables.tf at that tag; bump the version or remove the argument |
Invalid for_each argument ... depends on resource attributes that cannot be determined until apply | The map keys come from a resource not yet created | Use keys known at plan time (names from locals), not IDs |
| Plan wants to destroy and recreate a bucket after a refactor | A resource address changed without a moved block | Add moved { from = ... to = ... } and re-plan; expect "has moved" lines |
terraform test fails with credentials errors | The test is not using mock_provider | Add mock_provider "aws" {} at the top of the test file |
Error: Invalid provider configuration inside a module | Module declares its own provider block | Remove it and pass providers = { ... } from the root |
Failed to query available provider packages for >= 6.0, < 7.0 | Network or registry issue, or an unreleased version constraint | Check connectivity; loosen the constraint; run terraform init -upgrade |
Cost and cleanup
- Writing modules and running
terraform testcosts nothing. - The optional apply creates a KMS key (about 1 USD per month, prorated; scheduled deletion keeps it for the waiting period) and two empty S3 buckets (effectively free). ⚠ VERIFY current KMS pricing on the AWS KMS pricing page.
- Free alternative: skip the apply and rely on
terraform testplusterraform plan(the plan needs credentials to read the caller identity; exportAWS_PROFILE=learn-sandbox).
# Destroy everything the lab created (removes both buckets because force_destroy = true)
terraform destroy
# The KMS key enters its 7-day pending-deletion window; confirm nothing else remains
aws resourcegroupstaggingapi get-resources \
--tag-filters Key=Lab,Values=m10-l10 \
--profile learn-sandbox --region us-east-1 \
--query "ResourceTagMappingList[].ResourceARN"The tagging API can list a deleted resource for a short time; run it again after a minute.
Exercises
- 🟢 Guided: copy the module and root files above. Run
tf initandtf testinsidemodules/secure-bucket. All four runs should pass. Then break the regex invariables.tfand see which run fails. - 🟡 Challenge: add a variable
log_bucket_id(nullable). When set, enable S3 server access logging to that bucket with anaws_s3_bucket_loggingresource usingcount. Add two test runs: logging absent by default, logging present when the variable is set. Do not break existing callers. - 🔴 Live problem: a ticket arrives. "The Payments team's bucket must keep noncurrent versions for 7 years; every other team keeps 90 days. Also, the platform team wants to rename the module's output
bucket_arntoarnto match the registry style. Roll this out without an outage and without breaking forty callers." Describe your version numbers, your deprecation plan for the output, and what you put in the changelog.
Assignment
Create a terraform-modules folder in your portfolio repository with the secure-bucket module, its test file, a README documenting inputs and outputs, and a CHANGELOG.md with a v1.0.0 entry. Tag the commit v1.0.0 (a local tag is enough) and reference it from a root configuration using a git:: source. Add a short ADR (one page) listing three criteria you used to decide secure-bucket deserves to be a module and one resource you decided not to wrap.
Solutions
Expected tf test output: four runs, all pass. When you change the regex to accept uppercase letters, bad_name_is_rejected fails with "Expected failure ... but none occurred", which is exactly the signal you want: the test noticed the guard-rail loosened. Tests that only assert success would never have caught it.
Add to variables.tf:
variable "log_bucket_id" {
description = "Bucket that receives server access logs. Null disables logging."
type = string
default = null
}Add to main.tf:
resource "aws_s3_bucket_logging" "this" {
count = var.log_bucket_id == null ? 0 : 1
bucket = aws_s3_bucket.this.id
target_bucket = var.log_bucket_id
target_prefix = "${var.name}/"
}Tests: assert { condition = length(aws_s3_bucket_logging.this) == 0 ... } in a run with defaults, and == 1 in a run that sets log_bucket_id. Because the new variable defaults to null, existing callers see no change, so this is a minor version bump (v1.1.0). The log bucket needs its own permissions for S3 log delivery; that is outside this module on purpose.
For the live problem, a sound answer: add noncurrent_days already exists, so Payments passes noncurrent_days = 2555 (7 years) with no module change at all, and no version bump. For the rename, release v1.3.0 that adds a new output arn and keeps bucket_arn, mark bucket_arn deprecated in the README and changelog, announce a removal date, and remove it in v2.0.0. Removing an output is a breaking change for any caller that reads it.
Knowledge check
Answer: the folder where you run Terraform commands. Every configuration is a module; child modules are called from it. It is not a special kind of file; a root module is simply the top-level module, and any module can also be used as a child by another configuration.
Answer: the next terraform init -upgrade (or a fresh checkout in the pipeline) takes whatever is on main, so an unreviewed change can reach production. Use a tag or commit SHA. Pinning to a branch does not make the version immutable.
Answer: to prove that a validation rejects bad input. The run passes only if the named variable fails validation. Without it you only prove that valid input works.
Answer: a moved block (from = aws_s3_bucket.main, to = aws_s3_bucket.this). It tells Terraform the address changed but the real bucket is the same object. Running terraform state mv by hand also works but is not reviewable.
Answer: when it wraps a single resource and just re-exposes its arguments, or has only one caller. It adds an interface to maintain without hiding any complexity or enforcing any shared decision.
Interview questions
- How do you make sure forty teams build S3 buckets the same secure way? Publish a versioned
secure-bucketmodule with secure defaults and tests, let teams call it with a pinned version, and scan the plans in CI so a team cannot bypass it quietly. Pair it with an SCP or Config rule as a safety net for buckets created outside Terraform. - A module change must not break existing callers. What is your rule? Follow semantic versioning: additive changes with unchanged defaults are minor releases; removing or renaming inputs, outputs or resources without
movedblocks is a major release with a migration note. - Module or CDK construct, which would you choose? The same idea in two ecosystems. Choose by the team's tool, not by the abstraction: a C#-heavy team that deploys with CDK writes a construct; a team standardised on Terraform writes a module. See the decision lesson.
- How do you test Terraform without cloud credentials?
terraform testwithmock_providerfor logic and defaults,validatefor syntax, a policy scanner on the plan JSON, and one real deploy to a sandbox account for integration.
Certification practice
A platform team distributes a Terraform module for encrypted S3 buckets to many application teams. A change to the module must not reach production environments until it has been verified in a lower environment. Which approach meets the requirement?
A. Reference the module with ?ref=main so all teams always get the latest version.
B. Publish tagged versions and have each environment's configuration pin a specific tag, promoting the tag from dev to prod after verification.
C. Copy the module into each team's repository and let teams edit it.
D. Use a Terraform workspace named latest for the module.
Answer: B. Pinned versions make each upgrade an explicit, reviewable change that can be promoted environment by environment. A takes unreviewed changes. C recreates drift. D is not a versioning mechanism.
After a refactor, terraform plan shows that a production S3 bucket will be destroyed and recreated because a resource address changed. The bucket contains data. What should the engineer do before applying?
A. Apply anyway; S3 buckets are recreated with their data automatically.
B. Add a moved block from the old address to the new address and re-run the plan to confirm only a move is proposed.
C. Run terraform apply -refresh=false.
D. Delete the state file so Terraform starts again.
Answer: B. The moved block tells Terraform the real bucket is the same object. A is false: destroying a bucket deletes it (and a non-empty bucket cannot be deleted without emptying). C does not change the address mapping. D loses the record of every managed resource.
Completion checklist
- I can explain inputs, outputs and providers for a module in two sentences
- I ran
terraform testwith the mock provider and saw all runs pass - I called the module with
for_eachand read the outputs map - I can say why
?ref=mainis unsafe and what to use instead - I ran the cleanup steps (or skipped the optional apply) and confirmed nothing is still billing
Key takeaways
- A module is a folder with inputs, outputs and a provider requirement. Make the secure behaviour the default.
- Pin module versions by tag or SHA; modules run with your credentials and need review like any dependency.
- Use
movedblocks to refactor,validationto fail early andterraform testwith a mock provider to test without an account. - Do not wrap a single resource, and do not extract a module before a second caller exists.
- A CDK L3 construct plays the same role; choose by team skills and tooling.
Further reading
Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.
Terraform state
Move Terraform state into an encrypted, versioned S3 bucket with native lock files, see locking stop two applies racing each other, use workspaces carefully, and bring existing resources under management with import, moved and removed blocks.
Lab: one environment, two tools
Define the same NAT-free Fargate and PostgreSQL environment twice, in CDK (C#) and in Terraform, run both test suites without an account, deploy for under an hour, change it through a reviewed diff, detect drift with a tested C# report, destroy everything and write the ADR that picks one tool.