Dynamic Blocks

A dynamic block generates repeated nested blocks inside a resource from a collection — the tool for when a single resource needs N child blocks you do not want to write by hand. On GCP that is multiple allow rules in a google_compute_firewall, several env blocks in a Cloud Run container, or repeated IAM binding blocks within one resource.

The catch is that a dynamic block trades readability for brevity. Past a point — nested dynamics, dynamics over complex objects — a static block or a for_each on the whole resource is the clearer tool. The distinction the rest of this topic draws, between repeating a nested block and creating a whole resource, is the one that keeps configurations readable.

The Mechanism

A dynamic block has three parts: a label naming the nested block type it generates, a for_each supplying the collection, and a content block that is the template for each generated block. A dynamic "env" over a map of environment variables inside a Cloud Run container generates one env block per map entry — turning a variable-length set of blocks into data.

template {
  containers {
    image = "gcr.io/hatch-pipeline-dev/event-processor"
    dynamic "env" {
      for_each = var.env_vars
      content {
        name  = env.key
        value = env.value
      }
    }
  }
}

One input map drives every env block, so the event-processor service's environment is a single variable instead of a column of hand-written blocks.

The Iterator

Each generated block exposes an iterator named after the block label: inside the content of a dynamic "env", you reference env.key and env.value to fill the block from the current element. When the label collides with something else in scope, an iterator = e renames it so you reference e.key instead. The iterator is how each generated block reads its own element.

Firewall Allow Rules

A google_compute_firewall can carry several allow blocks, one per protocol-and-port set. A dynamic "allow" over a list of { protocol, ports } objects generates them from data, turning a variable-length rule set into an input variable instead of copy-pasted blocks. When the firewall needs three protocols in prod and one in dev, the difference is the input, not the resource.

resource "google_compute_firewall" "ingest" {
  name    = "hatch-ingest"
  network = google_compute_network.vpc.id
  dynamic "allow" {
    for_each = var.allow_rules
    content {
      protocol = allow.value.protocol
      ports    = allow.value.ports
    }
  }
}

The rule set lives in var.allow_rules as data; the resource generates one allow block per entry. Adding a rule is editing the variable, not the resource.

Cloud Run Env and Volumes

The same pattern fits a Cloud Run service's repeated env blocks and volume mounts. Driving them with a dynamic "env" over a map lets the service's environment be a single input the caller supplies, rather than a fixed set of hand-written blocks that has to be edited every time a variable is added or removed. The resource stays the same shape regardless of how many variables the environment carries.

When a Dynamic Block Hurts

Nested dynamics, and dynamics over complex objects, become unreadable fast — at two or three levels deep, no reviewer can tell what the resource generates. And there is a sharper boundary: if you are iterating to create whole resources — N buckets, N service accounts — that is a for_each on the resource, not a dynamic block. A dynamic block only generates nested blocks within one resource; it cannot create new addressable resources.

The Empty-Collection Case

A for_each over an empty map generates zero blocks cleanly. That is the idiomatic way to make a nested block optional — zero or more allow rules — without a separate conditional wrapping the block. Pass an empty collection and the block simply does not appear; pass entries and it generates one per entry. The optionality falls out of the collection's size.