Dynamic block syntax in Terraform - Deep Dive

Overview - Dynamic block syntax

What is it?

Dynamic block syntax in Terraform lets you create multiple nested blocks inside a resource or module based on a list or map. Instead of writing each block manually, you write a template that repeats for each item in your data. This helps when you want to manage many similar configurations without copying code. It makes your infrastructure code cleaner and easier to change.

Why it matters

Without dynamic blocks, you would have to write repetitive code for each nested block, which is error-prone and hard to maintain. Dynamic blocks solve this by automating repetition, saving time and reducing mistakes. This means you can manage complex infrastructure setups more easily and adapt quickly when requirements change.

Where it fits

Before learning dynamic blocks, you should understand basic Terraform resources, nested blocks, and how to use variables and loops like 'for_each'. After mastering dynamic blocks, you can explore advanced Terraform modules, complex expressions, and automation patterns.

Mental Model

Core Idea

Dynamic blocks let you write one block template that repeats automatically for each item in a list or map, generating multiple nested blocks in your Terraform configuration.

Think of it like...

Imagine you want to send the same invitation to many friends. Instead of writing each letter by hand, you write one letter template and fill in each friend's name automatically. Dynamic blocks do the same for Terraform blocks.

Resource or Module
┌───────────────────────────────┐
│ Static blocks                 │
│ ┌───────────────────────────┐ │
│ │ Dynamic block template     │ │
│ │ ┌───────────────────────┐ │ │
│ │ │ Repeats for each item  │ │ │
│ │ └───────────────────────┘ │ │
│ └───────────────────────────┘ │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Terraform nested blocks

Concept: Learn what nested blocks are and how they are used inside Terraform resources.

In Terraform, some resources have nested blocks to configure parts of the resource. For example, an AWS security group resource has nested 'ingress' blocks to define rules. Each nested block has its own settings inside the main resource block.

Result

You can write a resource with fixed nested blocks to configure specific parts of infrastructure.

Knowing nested blocks is essential because dynamic blocks generate these nested blocks automatically.

2

Foundation

Using for_each to repeat configurations

Concept: Learn how 'for_each' loops work in Terraform to repeat resource or block configurations.

Terraform's 'for_each' lets you create multiple instances of a resource or block by looping over a list or map. For example, you can create multiple security group rules by looping over a list of ports.

Result

You can write less code by looping over data to create repeated configurations.

Understanding 'for_each' prepares you to use dynamic blocks, which use a similar looping idea inside nested blocks.

3

Intermediate

Introducing dynamic block syntax

🤔Before reading on: do you think dynamic blocks replace entire resources or just nested blocks? Commit to your answer.

Concept: Dynamic blocks generate multiple nested blocks inside a resource or module based on input data.

A dynamic block has a 'for_each' expression and a 'content' block. Terraform repeats the 'content' block for each item in 'for_each', creating multiple nested blocks. This avoids writing many similar blocks manually.

Result

You can generate many nested blocks dynamically inside a resource, making code concise and flexible.

Knowing dynamic blocks only generate nested blocks—not whole resources—helps avoid confusion and misuse.

4

Intermediate

Syntax details of dynamic blocks

🤔Before reading on: do you think the 'content' block inside a dynamic block can have multiple nested blocks? Commit to your answer.

Concept: Learn the exact syntax of dynamic blocks, including 'for_each', 'iterator', and 'content'.

A dynamic block looks like this: dynamic "block_name" { for_each = var.list iterator = item # optional content { attribute = item.value # nested blocks or attributes } } The 'block_name' is the nested block type to create. 'for_each' loops over data. 'content' defines the block's body.

Result

You can write valid dynamic blocks that Terraform accepts and processes correctly.

Understanding the syntax fully prevents errors and lets you customize iteration with 'iterator'.

5

Intermediate

Using dynamic blocks with complex data

🤔Before reading on: can dynamic blocks handle maps or only lists? Commit to your answer.

Concept: Dynamic blocks can loop over lists or maps, allowing flexible data-driven block creation.

You can use dynamic blocks with maps by accessing keys and values inside 'content'. For example: dynamic "tag" { for_each = var.tags content { key = tag.key value = tag.value } } This creates one 'tag' block per map entry.

Result

You can generate nested blocks from complex data structures, adapting to many scenarios.

Knowing dynamic blocks work with maps expands their usefulness beyond simple lists.

6

Advanced

Combining dynamic blocks with conditionals

🤔Before reading on: do you think you can skip creating some blocks conditionally inside dynamic blocks? Commit to your answer.

Concept: You can use conditionals inside 'for_each' or inside 'content' to control which blocks get created or what they contain.

To conditionally create blocks, filter the data in 'for_each'. For example: dynamic "ingress" { for_each = [for rule in var.rules : rule if rule.enabled] content { from_port = ingress.value.from_port to_port = ingress.value.to_port protocol = ingress.value.protocol } } This creates blocks only for enabled rules.

Result

You can control block creation dynamically based on data conditions.

Understanding filtering in 'for_each' lets you write flexible, data-driven infrastructure code.

7

Expert

Performance and pitfalls of dynamic blocks

🤔Before reading on: do you think dynamic blocks always improve readability and performance? Commit to your answer.

Concept: Dynamic blocks can improve code reuse but may add complexity or obscure intent if overused or misused.

Using many dynamic blocks with complex expressions can make Terraform plans harder to read and debug. Also, dynamic blocks do not support all nested block types equally, and some providers may have quirks. Experts balance dynamic blocks with clarity and test carefully.

Result

You write maintainable, efficient Terraform code that uses dynamic blocks wisely.

Knowing when dynamic blocks help or hurt prevents technical debt and deployment issues.

Under the Hood

Terraform parses the configuration and evaluates the 'for_each' expression inside dynamic blocks. For each item, it generates a nested block in the internal resource model. This happens before the plan phase, so the plan and apply commands see the expanded blocks as if written manually. The iterator variable lets Terraform bind each item to names inside the block content.

Why designed this way?

Dynamic blocks were introduced to reduce repetitive code and improve maintainability. Before them, users copied nested blocks manually or used complex workarounds. The design balances flexibility with Terraform's declarative model, allowing dynamic repetition without losing readability or predictability.

Terraform Config
┌───────────────────────────────┐
│ Resource with dynamic block   │
│ ┌───────────────────────────┐ │
│ │ dynamic "block_name" {    │ │
│ │   for_each = data_list     │ │
│ │   content {                │ │
│ │     attributes             │ │
│ │   }                       │ │
│ │ }                         │ │
│ └───────────────────────────┘ │
└───────────────┬───────────────┘
                │
                ▼
Terraform Engine expands dynamic block:
┌───────────────────────────────┐
│ Resource with repeated blocks  │
│ ┌───────────────┐ ┌───────────┐│
│ │ block_name {} │ │ block_name {} │
│ │ block_name {} │ │ block_name {} │
│ └───────────────┘ └───────────┘│
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do dynamic blocks create new resources or just nested blocks? Commit to your answer.

Common Belief: Dynamic blocks create new resources automatically based on data.

Reality: Dynamic blocks only create nested blocks inside existing resources or modules, not new resources themselves.

Why it matters: Confusing this leads to wrong assumptions about resource counts and can cause deployment failures or unexpected infrastructure.

Quick: Can you use dynamic blocks anywhere in Terraform configuration? Commit to your answer.

Common Belief: Dynamic blocks can be used anywhere, including top-level resource attributes.

Reality: Dynamic blocks only work for nested blocks, not for top-level resource attributes or arguments.

Why it matters: Trying to use dynamic blocks incorrectly causes syntax errors and confusion.

Quick: Do dynamic blocks always make code simpler and easier to read? Commit to your answer.

Common Belief: Using dynamic blocks always improves code readability and maintainability.

Reality: Overusing dynamic blocks or using them with complex logic can make code harder to understand and debug.

Why it matters: Misusing dynamic blocks can increase technical debt and slow down troubleshooting.

Quick: Can dynamic blocks handle all nested block types equally well? Commit to your answer.

Common Belief: Dynamic blocks work perfectly with all nested block types in Terraform providers.

Reality: Some providers or nested block types have limitations or quirks with dynamic blocks, requiring workarounds.

Why it matters: Ignoring provider-specific behavior can cause unexpected errors or incomplete configurations.

Expert Zone

1

Dynamic blocks do not support all nested block attributes equally; some require static blocks for validation or provider compatibility.

2

The 'iterator' argument lets you rename the loop variable, which is crucial when nesting dynamic blocks to avoid naming conflicts.

3

Terraform evaluates dynamic blocks during the plan phase, so complex expressions inside can impact plan time and debugging.

When NOT to use

Avoid dynamic blocks when the nested blocks are few and static, as they add unnecessary complexity. For top-level resource repetition, use 'for_each' on the resource itself. When provider limitations exist, prefer static blocks or separate resources.

Production Patterns

In production, dynamic blocks are used to manage variable numbers of firewall rules, tags, or sub-resources like volumes or network interfaces. Teams combine dynamic blocks with modules and input validation to build reusable, scalable infrastructure templates.

Connections

Template engines

Dynamic blocks are similar to template engines that repeat content based on data.

Understanding how templates generate repeated content helps grasp how dynamic blocks automate nested block creation.

Loops in programming

Dynamic blocks use looping concepts like 'for_each' to repeat blocks, similar to loops in code.

Knowing programming loops clarifies how dynamic blocks iterate over data to produce multiple blocks.

Mass production in manufacturing

Dynamic blocks are like assembly lines that produce many identical parts efficiently.

Seeing dynamic blocks as mass production helps appreciate their role in automating repetitive infrastructure tasks.

Common Pitfalls

#1 Trying to use dynamic blocks to create multiple resources instead of nested blocks.

Wrong approach:

dynamic "aws_instance" {
for_each = var.instances
content {
ami = each.value.ami
instance_type = each.value.type
}
}

Correct approach:

resource "aws_instance" "example" {
for_each = var.instances
ami = each.value.ami
instance_type = each.value.type
}

Root cause:

Misunderstanding that dynamic blocks only generate nested blocks, not entire resources.

#2 Using dynamic blocks for top-level resource arguments instead of nested blocks.

Wrong approach:

resource "aws_security_group" "example" {
dynamic "name" {
for_each = ["sg1", "sg2"]
content {
value = name.value
}
}
}

Correct approach:

resource "aws_security_group" "example" {
name = "sg1"
# Use dynamic blocks only inside nested blocks, not for top-level attributes
}

Root cause:

Confusing nested blocks with resource attributes and misapplying dynamic block syntax.

#3 Overusing dynamic blocks with complex nested logic making code hard to read.

Wrong approach:

resource "aws_security_group" "example" {
dynamic "ingress" {
for_each = [for r in var.rules : r if r.enabled]
content {
from_port = ingress.value.from_port
to_port = ingress.value.to_port
protocol = ingress.value.protocol
dynamic "cidr_blocks" {
for_each = ingress.value.cidr_blocks
content {
cidr = cidr_blocks.value
}
}
}
}
}

Correct approach:

resource "aws_security_group" "example" {
dynamic "ingress" {
for_each = [for r in var.rules : r if r.enabled]
content {
from_port = ingress.value.from_port
to_port = ingress.value.to_port
protocol = ingress.value.protocol
cidr_blocks = ingress.value.cidr_blocks
}
}
}

Root cause:

Trying to nest dynamic blocks unnecessarily instead of using simpler attributes.

Key Takeaways

Dynamic block syntax in Terraform automates creating multiple nested blocks from lists or maps, reducing repetitive code.

They only generate nested blocks inside resources or modules, not entire resources themselves.

Understanding the syntax and how 'for_each' and 'content' work is essential to write valid dynamic blocks.

Dynamic blocks improve flexibility but should be used carefully to avoid complexity and provider limitations.

Mastering dynamic blocks helps build scalable, maintainable infrastructure as code that adapts to changing requirements.