Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท The HCL Language

for Expressions, Splat and Dynamic Blocks

Transform lists and maps with Terraform for expressions, filter with if, group with the ellipsis, use splat expressions and generate repeated nested blocks with dynamic.

Real configurations deal with collections: a list of subnets, a map of environments to sizes, a set of users. You often need to reshape them, such as turning a list of names into a map of tags, picking only the enabled items, or collecting the IDs of many resources. HCL gives you three tools for this: for expressions, splat expressions and dynamic blocks. If you know list comprehensions from Python or map and filter from JavaScript, you already know the idea.

The hcl examples are read-only; every one has a Python counterpart in the runnable blocks so you can see exactly what shape comes out.

for expressions on lists

The basic form transforms each element of a collection:

HCL
locals {
  names = ["web", "api", "db"]

  upper_names = [for n in local.names : upper(n)]            # ["WEB", "API", "DB"]
  prefixed    = [for n in local.names : "shop-${n}"]         # ["shop-web", ...]
  indexed     = [for i, n in local.names : "${i}-${n}"]      # ["0-web", "1-api", "2-db"]
}

Square brackets produce a list (more precisely a tuple). Curly braces produce an object/map:

HCL
locals {
  name_lengths = { for n in local.names : n => length(n) }   # { web = 3, api = 3, db = 2 }
}

The => arrow separates the key expression from the value expression. When you iterate over a map, the first variable is the key and the second the value:

HCL
locals {
  env_sizes   = { dev = "small", prod = "large" }
  descriptions = [for env, size in local.env_sizes : "${env} uses ${size}"]
  big_envs     = { for env, size in local.env_sizes : env => size if size == "large" }
}

Filtering with if

A trailing if keeps only elements for which the condition is true:

HCL
locals {
  users = [
    { name = "ada",   admin = true  },
    { name = "linus", admin = false },
    { name = "grace", admin = true  },
  ]
  admin_names = [for u in local.users : u.name if u.admin]   # ["ada", "grace"]
}

Duplicate keys and the grouping ellipsis

In an object-producing for, every key must be unique, otherwise Terraform reports "Duplicate object key". To group values that share a key, add ... after the value; each key then maps to a list:

HCL
locals {
  by_team = { for u in var.people : u.team => u.name... }
  # { web = ["ada", "grace"], data = ["linus"] }
}
Python for expressions as Python comprehensions (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Iterating over sets and objects

for accepts lists, sets, maps, objects and tuples. When the source is a set, there is no index: both forms give you the element. Sets of strings are sorted lexically in the result, so the order is deterministic. Because for returns a tuple rather than a list, you sometimes wrap it in tolist() or toset() when a function requires a precise type.

Splat expressions

A splat expression is a shorthand for "this attribute from every element". Use [*]:

HCL
output "instance_ids" {
  value = aws_instance.web[*].id
}

It is equivalent to [for i in aws_instance.web : i.id] for a list. A few facts:

  • It works on resources created with count (a list of objects). For for_each (a map of objects) use values(aws_instance.web)[*].id or a for expression.
  • On a single, non-list value, x[*] produces a one-element list, or an empty list when the value is null. That makes it handy for optional objects: var.settings[*] is [] when unset and [settings] when set.
  • The older legacy form .*.id still works but [*].id is preferred.
Python Splat and flatten (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Nested for and flatten

Nested loops need flatten because each inner for returns a list:

HCL
locals {
  rules = flatten([
    for env, ports in var.env_ports : [
      for port in ports : {
        key  = "${env}-${port}"
        env  = env
        port = port
      }
    ]
  ])
  rules_by_key = { for r in local.rules : r.key => r }
}

This two-step pattern (flatten into a list of objects, then convert to a map keyed by a unique string) is the standard way to feed nested data into for_each (count and for_each).

Dynamic blocks

Some resources have repeatable nested blocks, such as ingress rules in a security group or rule blocks in a lifecycle policy. When the number of blocks depends on data, generate them with a dynamic block:

HCL
variable "ingress_ports" {
  type    = list(number)
  default = [80, 443]
}

resource "aws_security_group" "web" {
  name = "web"

  dynamic "ingress" {
    for_each = var.ingress_ports
    content {
      from_port   = ingress.value
      to_port     = ingress.value
      protocol    = "tcp"
      cidr_blocks = ["0.0.0.0/0"]
    }
  }
}

How to read it: dynamic "ingress" produces zero or more nested blocks named ingress. for_each supplies the collection. Inside content, a temporary variable named after the block (ingress) has .key and .value (and iterator = x can rename it). With an empty collection, no blocks are generated, which makes dynamic a natural way to make a block optional.

Python Expanding a dynamic block (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Use dynamic blocks only when you truly need them. A configuration full of nested dynamic blocks is hard to read. If the shape is fixed (always two rules), write the blocks out by hand.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does [for n in ["a", "b"] : upper(n)] produce?

    Square brackets build a list/tuple from the transformed elements.
  2. 2. In { for u in users : u.team => u.name }, what happens when two users share a team?

    Keys must be unique. Add the grouping ellipsis (u.name...) to collect values into a list per key.
  3. 3. What is aws_instance.web[*].id equivalent to when web uses count?

    A splat collects one attribute from every element of a list into a list.
  4. 4. When is a dynamic block the right tool?

    dynamic generates repeated nested blocks from a collection. To repeat whole resources use count or for_each.

Summary

  • [for x in coll : expr] builds a list; { for x in coll : key => value } builds a map; if filters.
  • Add ... after the value to group duplicate keys into lists.
  • [*] (splat) pulls an attribute from every element; it also turns an optional object into a 0 or 1 item list.
  • Nested loops use flatten; then convert to a map with a unique key for for_each.
  • dynamic blocks generate repeated nested blocks from a collection; do not overuse them.

Next: Built-in Functions