Primitive vs complex types

Primitive types can only hold a single value. Terraform hass three: string, number an bool.

Complex types on the other hand group values together and come in two families:

  1. Collection types (lust, set, map) - holds many values that all need to match the same type.
  2. Structural types (object, tuple) hold values that can have different types, in a fixed shape.

You would mostly use these as a type constraint in variable blocks, for example:

type = list(string)

Terraform then rejects input that doesn't match.

Terraform converts between types where it safely can. "3" can become the number 3, and a tuple becomes a list if all its elements share the same type.

The keyword any accepts any type and lets Terraform infer it.

List and set

A list is an ordered sequence with values of the same type. Duplicates are allowed and you access by index, starting at 0. For example:

variable "locations" {
  type    = list(string)
  default = ["fsn1", "nbg1", "hel1"]
}

var.locations[0]          # "fsn1"
var.locations[2]          # "hel1"
length(var.locations)     # 3

A set is an unordered collection of unique values. There are no indexes and duplicates are also removed automatically.

So ["alice", "bob", "alice"] becomes ["alice", "bob"]

for_each does not accept lists, only map or a set of strings. To loop over a list, you would need to convert it first:

for_each = toset(var.locations)

Map and object

A map is a collection of key/value pairs. Keys are always strings, and all values muyst have the same type.

variable "server_types" {
  type = map(string)
  default = {
    dev  = "cx22"
    prod = "cx42"
  }
}

var.server_types["prod"]   # "cx42"
var.server_types.dev       # "cx22" (dot syntax also works)

An object also has named attributes, but each attribute has its own type and the set of attributes is fixed. Attributes can be made optional with a default.

variable "server" {
  type = object({
    name    = string
    backups = bool
    labels  = map(string)
  })
  default = {
    name    = "web-1"
    backups = true
    labels  = { env = "prod" }
  }
}

var.server.name            # "web-1"
var.server.backups         # true
var.server.labels["env"]   # "prod"

A map lets you use any keys, but every value must be the same type. An object has a fixed set of keys, but each value can be a different type.

Combining them is very common. A map of objects works well with for_each:

variable "servers" {
  type = map(object({
    type     = string
    location = string
  }))
  default = {
    web = { type = "cx22", location = "fsn1" }
    db  = { type = "cx42", location = "nbg1" }
  }
}

resource "hcloud_server" "this" {
  for_each    = var.servers
  name        = each.key              # "web", "db"
  server_type = each.value.type       # "cx22", "cx42"
  location    = each.value.location   # "fsn1", "nbg1"
  image       = "ubuntu-24.04"
}

Tuple

A tuple is an ordered, fixed-length sequence where each position has its own type.

Think of it as a list where every slot is typed separately.

variable "server_spec" {
  type    = tuple([string, number, bool])
  default = ["cx22", 2, true]
}

var.server_spec[0]   # "cx22" (string)
var.server_spec[1]   # 2      (number)
var.server_spec[2]   # true   (bool)

The length and types are both enforced, meaning these would fail:

["cx22", 2]            # too short, needs 3 elements
["cx22", "two", true]  # position 1 must be a number

A list can be any length, but every element is the same type.

A tuple has a fixed length and each element can have a different type.

You rarely declare tuples yourself, but you do use them all the time without noticing. Any literal in square brackets is a tuple. Terraform converts it silently to a list whenever all the elements share a type:

["a", 1, true]               # tuple: mixed types, stays a tuple
["fsn1", "nbg1"]             # tuple, converted to list(string) when needed