Dynamic Blocks

A dynamic block generates repeated nested blocks inside a resource from a collection — multiple ingress rules in a security group, multiple setting blocks in a resource — when you can't simply set an argument to a list. They earn their place when the count of nested blocks is genuinely data-driven, and they are easy to overuse: a config wallpapered in dynamic blocks is often harder to read than the explicit version it replaced.

The distinction that makes them necessary is between an argument and a nested block. An argument takes a value, including a list, directly. A nested block is structural — ingress { ... } is not a value you can assign a list to — so when you need a variable number of them, a dynamic block is the mechanism that produces them.

The Problem They Solve

A security group's ingress is a nested block, not a list argument. You can write three ingress { ... } blocks by hand, but you cannot bind ingress to a variable-length list of rules. When the number of rules comes from a variable that changes per environment, that is exactly the gap a dynamic block fills.

Anatomy of a Dynamic Block

A dynamic "ingress" block takes a for_each over a collection and a content block that defines one generated block per element. Inside content, an iterator object — named after the block by default — exposes .key and .value for the current element. The result is one ingress block per element of the collection.

resource "aws_security_group" "app" {
  name = "app-sg"

  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]
    }
  }
}

A Worked Source Variable

The source for that loop is a clearly-typed variable: a list of objects, each with a port and a cidr. Typing it as list(object({...})) makes the shape obvious to anyone reading the variable, and the validation that comes with a precise type catches a malformed rule at plan time rather than mid-apply.

variable "ingress_rules" {
  type = list(object({
    port = number
    cidr = string
  }))
  default = [
    { port = 443, cidr = "0.0.0.0/0" },
    { port = 22,  cidr = "10.0.0.0/8" },
  ]
}

The Iterator and Nesting

The iterator defaults to the block's name but can be renamed with iterator = name, which matters when you nest one dynamic block inside another and need to tell the two levels apart. Nesting is where readability falls off a cliff: a dynamic block inside a dynamic block inside a resource quickly becomes something nobody can read at a glance, and that cost is real even when it works.

When Not to Use Them

A fixed, small set of nested blocks is clearer written out. Generating two or three static ingress blocks with a dynamic block trades explicit, greppable config for indirection that buys nothing — the count never varies. Reserve dynamic blocks for the case where the number of blocks genuinely comes from data, and write the rest out by hand.