Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Providers and Resources

count and for_each: Creating Many Resources

Create many similar resources with Terraform count and for_each: syntax, addresses, count.index, each.key, the index-shift problem, toset, maps, modules and when to choose which.

One resource block can create more than one real object. If you need three web servers, ten DNS records or a bucket per environment, you do not copy and paste the block. You use one of two meta-arguments: count, which repeats a block a number of times, or for_each, which creates one instance per item of a map or set. Both are essential, and choosing the wrong one is behind some of the most painful Terraform surprises, especially accidental destroys.

The HCL is read-only; the Python stand-ins mimic how a block expands into instances and what happens to their addresses when the input changes.

count

count takes a whole number, and the block is created that many times. Inside the block, count.index is the zero-based position:

HCL
resource "aws_instance" "web" {
  count         = 3
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"

  tags = {
    Name = "web-${count.index}"
  }
}

The instances have addresses aws_instance.web[0], aws_instance.web[1] and aws_instance.web[2]. Refer to one with aws_instance.web[1].id, or to all of them with a splat: aws_instance.web[*].id (splat). count = 0 creates none, which is how the pattern count = var.enabled ? 1 : 0 makes a resource optional (conditionals). Remember to refer to optional single instances as aws_eip.web[0] or with one(aws_eip.web[*].id).

count can also be driven by the length of a list:

HCL
variable "names" {
  type    = list(string)
  default = ["alpha", "beta", "gamma"]
}

resource "aws_s3_bucket" "team" {
  count  = length(var.names)
  bucket = "acme-${var.names[count.index]}"
}

The index-shift problem

Here lies the trap. Instances made with count are identified by position. Remove "alpha" from the list above, and beta moves from index 1 to 0, gamma from 2 to 1. Terraform sees that aws_s3_bucket.team[0] should now be named acme-beta and [1] acme-gamma: it plans to rename or replace the first two buckets and destroy the third. Deleting something at the front or middle of a list shuffles everything behind it.

Python count addresses shift when the list changes (stand-in)

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.

Removing one item causes two replacements and a deletion. For buckets or databases this can mean data loss. This is why count is best for identical, interchangeable things (three equal web servers) or on/off switches (0 or 1), and not for collections of things with identities.

for_each

for_each creates one instance per element of a map or a set of strings, and identifies each instance by its key, not its position:

HCL
resource "aws_s3_bucket" "team" {
  for_each = toset(["alpha", "beta", "gamma"])
  bucket   = "acme-${each.key}"
}

Addresses are aws_s3_bucket.team["alpha"], ["beta"], ["gamma"]. Remove "alpha" and only that bucket is planned for destruction; the others are untouched. Inside the block, each.key is the key and each.value is the value. For a set they are identical. With a map they differ, and you can carry settings per instance:

HCL
variable "servers" {
  type = map(object({
    size = string
    zone = string
  }))
  default = {
    web = { size = "t3.small", zone = "a" }
    api = { size = "t3.medium", zone = "b" }
  }
}

resource "aws_instance" "app" {
  for_each      = var.servers
  ami           = data.aws_ami.ubuntu.id
  instance_type = each.value.size
  subnet_id     = aws_subnet.zone[each.value.zone].id

  tags = { Name = each.key }
}

Reading instances: aws_instance.app["web"].id. To collect all IDs, use values(aws_instance.app)[*].id or { for k, v in aws_instance.app : k => v.id }.

Python for_each keeps stable addresses (stand-in)

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.

Only the removed key is touched, and changing one server's size updates just that instance.

Rules and limitations of for_each

  • The value must be a map or a set of strings. A list of strings is rejected; wrap it with toset(var.names). A list of objects must first be turned into a map: { for s in var.servers : s.name => s }.
  • Keys must be known at plan time. If they derive from an attribute that only exists after apply (such as the ID of another resource), you get "The for_each set includes values derived from resource attributes that cannot be determined until apply." Derive keys from variables or fixed values, and use the values for computed data.
  • Keys cannot be sensitive values, since they appear in the plan output and addresses.
  • You cannot use count and for_each on the same block.
  • Use only one of them per block, but you can combine layers: modules can themselves use for_each.

Choosing between them

Situation Use
Optional resource (0 or 1) count = cond ? 1 : 0
N identical, interchangeable instances count
Instances with their own identity or settings for_each over a map or set
List that may change in the middle for_each with a map keyed by a stable name
Nested data (environments x ports) flatten and a keyed map for for_each

When in doubt, choose for_each. Its addresses carry meaning and survive reordering.

Converting from count to for_each

Changing the meta-argument changes every address, so Terraform wants to destroy and recreate everything. Avoid that with moved blocks that map old addresses to new ones:

HCL
moved {
  from = aws_s3_bucket.team[0]
  to   = aws_s3_bucket.team["alpha"]
}
moved {
  from = aws_s3_bucket.team[1]
  to   = aws_s3_bucket.team["beta"]
}

Then plan: the output should say "has moved to", with nothing to change.

count and for_each on modules

Both work on module blocks too, creating a whole copy of a module per instance. Module instances appear in addresses as module.network["prod"].aws_vpc.main. The same rules apply.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You create buckets with count = length(var.names) and delete the first name from the list. What is the risk?

    count identifies instances by position. Removing an early element shifts all later indexes and causes unrelated replacements.
  2. 2. What can for_each iterate over?

    for_each needs a map or a set of strings. Convert a list with toset() or build a map with a for expression.
  3. 3. What is the address of the instance for key "web" created with for_each on aws_instance.app?

    for_each instances are addressed by key in square brackets with quotes.
  4. 4. Why does 'The for_each set includes values derived from resource attributes that cannot be determined until apply' happen?

    Terraform must know how many instances and which keys exist while planning. Build keys from variables or constants.

Summary

  • count repeats a block N times with count.index; addresses are type.name[0].
  • for_each creates one instance per map entry or set element with each.key and each.value; addresses use keys.
  • count breaks when list items are removed from the middle; prefer for_each for things with identity.
  • for_each needs a map or a set of strings with keys known at plan time.
  • moved blocks convert between schemes without destroying real objects.
  • Use count = cond ? 1 : 0 for optional resources.

Next: Lifecycle Rules and Provisioners