count vs for_each

Almost every "I need several of these" decision comes down to count versus for_each, and getting it wrong is not a style nit — it determines whether editing the collection later is a no-op diff or a destructive renumber. The rule fits in a sentence: use count for an ordered set of interchangeable replicas, use for_each for a keyed set of distinct things, and treat for_each as the default because most real collections are keyed.

The two previous topics covered each construct in isolation. This one is about the choice between them, the one decision that has the largest downstream consequence in this chapter. It also covers the unpleasant case you will eventually face: an existing count collection that should have been for_each from the start, and how to convert it without an outage.

Positional vs Keyed

count addresses instances by index — [0], [1], [2]. for_each addresses them by key — ["billing"], ["orders"]. That address is not a display detail; it is the identity Terraform records in state and uses to match config against reality on the next plan. The whole comparison reduces to this: one identity scheme is a position that shifts, the other is a key that does not.

What Changes When the Collection Changes

Under count, removing a non-last element shifts every later index down by one, and because the address is the identity, Terraform reads each shifted position as a different resource — it churns the tail with destroys and recreates. Under for_each, removing an entry touches only that key; every other instance keeps its address and its state untouched. This single behavioral difference decides most cases before you even reach the heuristic.

For the Hatch pipeline this is the difference between safe and dangerous. The source list, the event-type list, and the consumer list all grow and shrink over time. Keyed by name under for_each, every add and remove is surgical. Keyed by position under count, removing the billing source from the middle would destroy and recreate every bucket after it, losing their contents.

The Decision Heuristic

Ask one question. "Are these N interchangeable copies where order is meaningless and stable?" — then count. "Are these distinct things I identify by name?" — then for_each. When you are unsure, choose for_each; the cost of for_each on a collection that turns out to be fixed is nothing, while the cost of count on a collection that turns out to be keyed is a destructive renumber the first time someone edits it.

Converting count to for_each

Switching an existing counted resource to for_each re-addresses every instance from [0] to ["key"]. Terraform sees the old addresses in state and the new addresses in config, finds no match, and reads it as destroy-everything-and-recreate — unless you tell it the addresses are the same resource under a new name. You do that by remapping, either with moved blocks in the configuration or with terraform state mv on the command line.

moved {
  from = google_pubsub_topic.events[0]
  to   = google_pubsub_topic.events["orders"]
}

moved {
  from = google_pubsub_topic.events[1]
  to   = google_pubsub_topic.events["clicks"]
}

The Migration Mechanics

A moved block per instance — from = google_pubsub_topic.events[0] to to = google_pubsub_topic.events["orders"] — tells Terraform the resource at the old address is the same object now living at the new one, so the plan shows zero changes. Without it, swapping a loop construct from count to for_each takes a full outage as every topic, bucket, and account is destroyed and recreated, which is an absurd price for what is mechanically a refactor. Write the moved blocks, confirm the plan reports no destroys, then apply.