Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท Modules

count, for_each and Testing with Modules

Create many module instances with for_each and count, pass maps of settings, avoid index-shift bugs and write native terraform test files for your modules.

A module is most powerful when you can stamp it out many times from data: one queue per team, one bucket per environment, one database per tenant. Terraform lets you put count or for_each on a module block, exactly as on a resource. This lesson shows when to use each, the classic bug that count causes, and how to test a module with Terraform's built-in terraform test command.

for_each on a module

Give for_each a map (or a set of strings) and you get one instance per key. Inside the call, each.key and each.value describe the current item:

HCL
variable "teams" {
  type = map(object({
    retention_days = number
    alarm_email    = string
  }))
  default = {
    payments = { retention_days = 30, alarm_email = "[email protected]" }
    search   = { retention_days = 7,  alarm_email = "[email protected]" }
  }
}

module "queue" {
  source   = "./modules/queue"
  for_each = var.teams

  name           = "${each.key}-jobs"
  retention_days = each.value.retention_days
  alarm_email    = each.value.alarm_email
}

output "queue_urls" {
  value = { for team, m in module.queue : team => m.url }
}

The addresses become module.queue["payments"] and module.queue["search"]. Adding a third team creates only the new instance; removing search destroys only its resources. The other instances are untouched because the keys are stable.

count and the index-shift trap

count creates instances numbered 0, 1, 2.... That is fine for "N identical copies" or an on/off switch:

HCL
module "monitoring" {
  source = "./modules/monitoring"
  count  = var.enable_monitoring ? 1 : 0
}

But using count over a list of distinct things is a trap. Suppose you create buckets from ["logs", "assets", "backups"] with count. Remove "assets", and backups slides from index 2 to index 1: Terraform now plans to rename the bucket at index 1 and destroy the one at index 2. With for_each, keys do not shift. The simulation shows the difference.

Python Why for_each beats count for lists

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Rule of thumb: use count for identical copies or a 0/1 switch; use for_each whenever each instance has its own identity. With for_each, keys must be known at plan time: they cannot depend on attributes of resources that have not been created yet (the error is "Invalid for_each argument"). Derive them from variables, locals or existing data instead.

You can convert a list into a map in the call:

HCL
for_each = { for s in var.subnets : s.name => s }
# or, for a list of strings
for_each = toset(var.names)

Referencing instances

HCL
module.queue["payments"].url            # one instance
[for m in module.queue : m.url]         # all urls as a list
{ for k, m in module.queue : k => m.url } # all urls as a map
module.monitoring[0].dashboard_url      # a counted instance
one(module.monitoring[*].dashboard_url) # null if count = 0, else the value

one() is handy for the on/off switch: it returns the single element or null for an empty list.

Python Expanding for_each in a module call

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Testing modules with terraform test

Terraform 1.6 added a native test framework. Test files end in .tftest.hcl and live in the module (or a tests/ folder). Each run block executes a plan or apply, then assert blocks check conditions:

HCL
# tests/basic.tftest.hcl
variables {
  name           = "demo-jobs"
  retention_days = 7
  alarm_email    = "[email protected]"
}

run "creates_queue_with_retention" {
  command = plan

  assert {
    condition     = aws_sqs_queue.this.message_retention_seconds == 604800
    error_message = "Retention should be 7 days in seconds."
  }
}

run "rejects_bad_email" {
  command = plan

  variables {
    alarm_email = "not-an-email"
  }

  expect_failures = [var.alarm_email]
}

Run terraform test. Plan-mode tests are fast and free; command = apply creates real resources and destroys them afterwards, so use it in a sandbox account. From 1.7 you can add mock_provider "aws" {} blocks, so tests run without any credentials or cloud calls, which is ideal for CI on every commit.

The stand-in below mimics the shape of a test run: named runs, assertions with messages and expected failures.

Python A mini test runner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

depends_on and providers for modules

Modules accept depends_on, but use it only when a real hidden dependency exists (for example an IAM policy that the module's code needs but never references). To use a different provider configuration (another region or account), pass it explicitly:

HCL
module "replica" {
  source    = "./modules/bucket"
  providers = { aws = aws.eu_west }
}

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is for_each safer than count for a list of distinct buckets?

    Removing an item from the middle of a counted list renumbers the rest and causes unwanted replacements.
  2. 2. How is one instance of module.queue created with for_each addressed?

    for_each instances use their key in brackets.
  3. 3. Which file extension do native Terraform tests use?

    terraform test discovers *.tftest.hcl files.
  4. 4. What does mock_provider allow?

    A mocked provider returns generated values, so plan and apply tests need no cloud account.

Summary

  • for_each on a module gives one instance per key; count is for identical copies and 0/1 switches.
  • Never use count over a list of distinct items; keys, not positions, should identify instances.
  • Keys must be known at plan time.
  • terraform test runs .tftest.hcl files with run, assert and expect_failures; mock_provider removes the need for credentials.
  • Pass providers = {...} to a module when it needs another region or account.

Next: The Plan and Apply Workflow