Terraform for_each Meta-Argument: Map/Set-Based Resource Generation

Terraform's for_each is a meta-argument that stably generates multiple instances from a collection (mainly a map or set). On the exam, the differences from count, the meaning of each key, and the stability of instance addresses are common topics.

This article covers when to use map vs set generation in practice, common pitfalls, how to apply for_each to modules, and what to focus on for the exam. We stick to stable concepts grounded in the official documentation and avoid version-specific behavior.

for_each Basics and Exam Perspective

for_each accepts a map or a set (typically a set of strings) and produces one resource (or module) instance per element. Each instance is addressed by its key, which makes it resilient to reordering and prevents unintended diffs.

Inside the resource or module block, you can reference each.key and each.value. For maps, key is the map key and value is the corresponding value (which can also be an object). For sets, key and value are the same string. At the Associate level, expect questions on the differences vs count (addressing, stability), how to choose between map and set, and type conversions (toset, tomap, keys, etc.).

• for_each accepts a map (recommended) or a set (of strings)
• Each instance is addressed by a key, like resource.type.name["key"]
• You can use each.key / each.value (including inside module call blocks)
• Sets are unordered, but because key == value (a string), addresses tend to stay stable
• count is index-based and brittle under reordering; if instances have names, for_each is the better choice

Minimal example: generating null_resource from a map

variable "services" {
  type = map(object({
    size = number
  }))
  default = {
    web = { size = 2 }
    api = { size = 1 }
  }
}

resource "null_resource" "svc" {
  for_each = var.services

  triggers = {
    name = each.key
    size = tostring(each.value.size)
  }
}

# Example addresses:
# null_resource.svc["web"], null_resource.svc["api"]

for_each with Maps: Stable Generation of Named Instances

Because maps carry keys, they are ideal for stably creating named instances. Putting an object in the value lets you pack per-instance settings into it. Additions and deletions are detected per key, so addresses do not wobble.

In practice, the standard pattern is to feed for_each a map(object(...)) keyed by an ID or logical name. A key change is treated as destroying the old key and creating a new one, so it is important to design keys that you will not casually change, to avoid unintended rollouts.

• Keys are the single most important factor for determining instance addresses
• Values can be objects; reference per-instance attributes via each.value
• A key change is not a rename; it is treated as a destroy plus a new create

Mapping between map keys and resource addresses

Concrete example using map(object)

variable "instances" {
  type = map(object({
    cpu = number
    mem = number
    tags = map(string)
  }))
}

resource "null_resource" "node" {
  for_each = var.instances

  triggers = {
    name = each.key
    cpu  = tostring(each.value.cpu)
    mem  = tostring(each.value.mem)
  }
}

# Reference example: null_resource.node["web"].id

for_each with Sets: Existence-Flag-Style Generation

A set is an unordered collection of strings. It works well when all you need to express is whether a given name exists. Because each instance's address is based on its element string, addresses stay stable as long as the set membership does not change. Duplicates are removed automatically.

Sets do not carry value information, so if you need to attach attributes, use a map instead, or resolve the extra data through another data source. Note that converting a list with toset loses the original ordering.

• each.key and each.value are equal; both are the element string
• Duplicates are absorbed; ordering is undefined
• If you need detailed attributes, switch to map(object)

Example with a set of strings

locals {
  names = toset(["web", "api", "web"])  # duplicate "web" is automatically removed
}

resource "null_resource" "role" {
  for_each = local.names

  triggers = {
    name = each.key  # == each.value
  }
}

# Reference example: null_resource.role["api"].id

count vs for_each: Comparison and Selection Criteria

count is simple and powerful, but because it depends on indexes, reordering or inserting/deleting items in the middle easily causes instance churn. If you can manage by name, for_each gives you stability.

On the Associate exam, common questions ask which one to use and why diffs are more stable with for_each.

• Use for_each when you can name instances, and count when you simply need more of them
• Migrating from existing count requires careful key design and use of moved blocks or state mv
• Attributes that a set cannot carry should be expressed with map(object)

Safe migration from count to for_each (example)

# Old: created with count (brittle under reordering)
# resource "null_resource" "srv" {
#   count = length(var.names)
#   triggers = { name = var.names[count.index] }
# }

# New: convert to a map and use for_each (stable)
locals {
  names_map = { for n in var.names : n => { name = n } }
}
resource "null_resource" "srv" {
  for_each = local.names_map
  triggers = { name = each.key }
}

# If the mapping between existing resources and keys changes,
# use terraform state mv or a moved block to make the mapping
# explicit and migrate without downtime.

for_each on Modules and Design Patterns

You can also apply for_each to a module call. Inside the calling module block, reference each.key / each.value and pass them as inputs to the submodule. Inside the submodule itself, each is not available, so receive values via regular variables.

Managing a fleet of apps with a map(object) — using a logical name as the key and a configuration object as the value — is the most stable pattern in practice. Outputs are referenced as module.block["key"].output.

• Use each on the caller side; inside the submodule, reference variables instead
• It is important to fix keys to logical names and design them to stay invariant
• Reference outputs as module.x["key"].out

for_each on a module call

variable "apps" {
  type = map(object({
    image = string
    replicas = number
  }))
}

module "app" {
  source  = "./modules/app"
  for_each = var.apps

  name     = each.key
  image    = each.value.image
  replicas = each.value.replicas
}

# Reference example: module.app["frontend"].endpoint

# modules/app/variables.tf
# variable "name" { type = string }
# variable "image" { type = string }
# variable "replicas" { type = number }

Common Pitfalls and Debugging Essentials

A key change triggers resource replacement. Pick keys that are immutable identifiers (logical names or IDs), and keep mutable information like display names inside the value object. Converting a list with toset loses ordering, so do not mix in logic that assumes a specific order.

When refactors require mapping existing addresses to new keys, migrate manually with terraform state mv or place a moved block in the configuration to prevent unplanned destruction. Use terraform plan to inspect diffs and terraform state list to check addresses.

• Keep keys immutable; push mutable information into each.value
• Sets dedupe and are unordered; do not assume order-dependent processing
• During refactors, migrate safely using state mv or moved blocks
• Apply filters at the comprehension stage when building the map (using an if clause)

Filtering and key-design example

locals {
  # Limit to apps on a stable version, keyed by logical name
  filtered = {
    for name, cfg in var.apps :
    name => cfg
    if startswith(cfg.version, "stable-")
  }
}

module "app" {
  source   = "./modules/app"
  for_each = local.filtered
  name     = each.key
  version  = each.value.version
}

# Debugging:
# terraform plan
# terraform state list | grep module.app

Check Your Understanding

Frequently Asked Questions