count

count is the oldest way to stamp out multiple copies of a resource: set count = 3 and Terraform creates three instances, addressed resource.name[0], [1], [2], with count.index available inside the block to vary each one. It is index-based and positional, which is exactly its strength for identical-ish replicas and exactly its footgun the moment the middle of the list changes.

The Hatch pipeline reaches for iteration as it outgrows its single raw bucket. count is the simplest construct that gets there, and for a fixed number of interchangeable things it is the right tool. But most real collections are named and mutable rather than fixed and positional, and on those count does something destructive that the next topic, for_each, exists to avoid. Knowing where the line falls is the whole point of this page.

The Basic Form

Setting count = N on a resource tells Terraform to create N instances of it, indexed 0 through N-1. Inside the block, count.index is the current instance's number, so each copy can differ — a numbered name, a zone pulled from a list by index, a label carrying the index. Without count.index you would get N identical resources, which the provider usually rejects because names must be unique.

resource "google_compute_instance" "worker" {
  count        = 3
  name         = "hatch-worker-${count.index}"   # hatch-worker-0, -1, -2
  machine_type = "e2-standard-2"
  zone         = "us-central1-a"
}

That block produces three instances with distinct names, addressed google_compute_instance.worker[0] through [2]. They are interchangeable workers where the index is just a serial number, which is precisely the case count handles cleanly.

Iterating a List with count

A common pre-for_each pattern is to drive count off the length of a list and index back into that list with count.index. Setting count = length(var.regions) creates one resource per element, and var.regions[count.index] pulls the matching element for each instance. This walks a list to produce "one resource per element," the original idiom before for_each existed.

variable "regions" {
  type    = list(string)
  default = ["us-central1", "europe-west1", "asia-east1"]
}

resource "google_storage_bucket" "regional" {
  count    = length(var.regions)
  name     = "hatch-events-${var.regions[count.index]}"
  location = var.regions[count.index]
}

This works, and you will see it in older code. It also carries the positional trap front and center: the buckets are keyed by their position in the list, not by region name, so the list's order is now load-bearing state.

Addressing Instances

Once count is set, the resource is no longer a single object — it is a list of instances. You address one with an index, google_storage_bucket.regional[0].name, and all of them at once with a splat, google_storage_bucket.regional[*].name, which yields the list of every instance's name. A bare reference without an index, google_storage_bucket.regional.name, is an error: Terraform cannot tell which of the instances you mean.

This is the first thing that bites newcomers. Adding count to an existing single resource silently changes its type from one object to a list, and every reference elsewhere in the configuration must be updated to index in. The splat form, covered in its own topic later in this chapter, is how you read an attribute across all instances at once.

The Renumbering Footgun

Here is the behavior that decides whether count is right for a given collection. Instances are keyed by position. Remove the element at index 1 of a three-element list and index 2 shifts down to 1, index 3 shifts to 2 — Terraform compares the new positions to state and reads it as "destroy the resource at index 2 and recreate it, destroy the resource at index 1 and recreate it," not "delete the middle one and leave the rest alone." That destructive churn has dropped buckets and disks in production, taking their contents with them.

Concretely: a list of three source buckets keyed by position, and you remove hatch-events-raw-billing from the middle. The plan does not say "delete one bucket." It proposes destroying and recreating every bucket after the removed one, because each one's positional address now points at different data. The bucket that used to be index 2 is now index 1, and Terraform tears it down to rebuild it at its new slot. Nothing about the change you intended implied data loss, but the positional model produced it.

When count Is Still Right

count earns its place for a fixed number of truly interchangeable replicas where order never changes — N identical worker VMs behind a load balancer, where instance 0 and instance 2 are indistinguishable and no element is ever removed from the middle. It is also the mechanism behind the conditional count = var.enabled ? 1 : 0 idiom for creating a resource or not, which gets its own treatment in the conditional-expressions topic. Anything keyed, named, or mutable in the middle wants for_each instead.