Complex Types
Lists, sets, maps, objects and tuples in Terraform.
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:
- Collection types (lust, set, map) - holds many values that all need to match the same type.
- 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