Dynamic Blocks

## Arguments take values; blocks are syntax Terraform configuration mixes two things. **Arguments** take values: `name = "web"`, and any expression that produces a value can fill one. **Nested blocks** are part of the resource type's schema: `ingress { ... }` inside `aws_security_group` is written out, one block per rule. No expression evaluates to "a list of blocks", because blocks are not values. That is fine while the rules are fixed. It breaks when the rules come from an input variable, differ per environment, or are assembled by a module for its callers. The `dynamic` block is the escape hatch: a meta-block that tells Terraform to *generate* nested blocks from a collection. ## Anatomy ```hcl dynamic "ingress" { # label = the nested block type to generate for_each = var.rules # one element per generated block iterator = rule # optional: rename the temp variable content { # the body of each generated block from_port = rule.value.port } } ``` Four parts matter: - **The label** is the name of the nested block type being produced. `dynamic "ingress"` produces `ingress` blocks; the label must be a block type the resource, data source, provider or provisioner actually accepts. - **`for_each`** accepts a list, a set, or a map. Unlike a resource's `for_each`, a list is allowed here, because generated blocks have no state addresses to key. - **`content`** is mandatory. It is the template body, evaluated once per element. - **The temporary variable** is named after the label unless `iterator` renames it. It exposes `.key` and `.value`. ## What key and value hold - **List** — `.key` is the element's index, `.value` is the element. - **Map** — `.key` is the map key, `.value` is the map value; elements come out in lexical key order. - **Set** — `.key` is identical to `.value`; the documentation says not to use `.key` with a set. This is why security-group examples usually take `list(object(...))` or `map(object(...))`: each element carries every field the block needs. ## The security-group shape ```hcl variable "ingress_rules" { type = list(object({ port = number, cidr_blocks = list(string) })) } resource "aws_security_group" "web" { name = "web" dynamic "ingress" { for_each = var.ingress_rules content { from_port = ingress.value.port to_port = ingress.value.port protocol = "tcp" cidr_blocks = ingress.value.cidr_blocks } } } ``` All the generated blocks belong to the single `aws_security_group.web` resource. They are attributes of one object in state, not separate addressable things. ## The zero-or-one idiom Because an empty collection generates no blocks at all, a conditional list is the standard way to make a whole nested block optional: ```hcl dynamic "logging" { for_each = var.enable_logging ? [1] : [] content { target_bucket = var.log_bucket } } ``` One element means one block; the empty list means the block is simply absent, which is exactly what a provider needs when "absent" and "present but empty" mean different things. ## Three things it is not 1. **Not a way to create resources.** A resource's own `for_each` or `count` creates multiple resource instances with their own state addresses. A `dynamic` block creates repeated *blocks inside one* resource instance. 2. **Not for arguments.** `tags` on most AWS resources is a map argument, not a block, so you build it with an expression such as `merge(var.common_tags, { Name = "web" })` — a dynamic block cannot produce it. 3. **Not free.** Generated configuration is harder to read and to review than blocks written out literally, and each generated block loses the individual identity that a separate resource would have had. HashiCorp's own guidance is to reach for `dynamic` mainly when a reusable module needs to hide repetition behind a clean interface.