Terraform fot d lookup()

This is part of an ongoing series of posts documenting the built-in interpolation functions in Terraform. For more information, check out the beginning post. In this post I am going to cover the lookup() function. The example file is on GitHub here.

What is it?

Function name: lookup(map, key, [default])

Returns: Takes a map, a key, and an optional default value. Returns the value in the map that corresponds to the key if found. If not found, returns the optional default value or throws an error.

Example:

variable "map" {
  type = map

  default = {
    "one" = "1"
  }
}

# Returns 1
output "lookup_output" {
  value = "${lookup(var.map, "one")}"
}

Example file:

##############################################
# Function: lookup
##############################################
##############################################
# Variables
##############################################
variable "map_value" {
  type = "map"

  default = {
    "life"       = "42"
    "universe"   = "6"
    "everything" = "7"
  }
}

variable "empty_map" {
  type = "map"

  default = {}
}

variable "nested_map" {
  type = "map"

  default = {
    "Zaphod" = {
      "First" = "Zaphod"
      "Last" = "Beeblebrox"
    }

    "Arthur" = {
      "First" = "Arthur"
      "Last" = "Dent"
    }
  }
}

variable "lookup_key" {
  default = "life"
}

variable "default_key" {
  default = "Trillian"
}



##############################################
# Resources
##############################################

##############################################
# Outputs
##############################################

output "1_map_value_output" {
  value = "${lookup(var.map_value,var.lookup_key,var.default_key)}"
}
output "2_empty_map_output" {
  value = "${lookup(var.empty_map,var.lookup_key,var.default_key)}"
}

#Nested maps not allowed.
#Will work if you specify a non-existent key and a default value
#output "3_nested_map_output" {
#  value = "${lookup(var.nested_map,var.lookup_key,var.default_key)}"
#}

Run the following from the lookup folder to get example output for a number of different cases:

#Basic use
terraform apply

#Alternate key
terraform apply -var "lookup_key=everything"

#Non-existent key
terraform apply -var "lookup_key=missing"

Why use it?

This has got to be one of the most used functions in Terraform. There are a ton of data sources that return a map of values you might want to parse through. AWS AMIs, Azure VMs, firewall rules, metadata tags. That’s just a few off the top of my head. If you’ve got a map of key pairs, lookup is your pal.

Lessons Learned

The documentation on the Terraform site states that the function will not work with nested maps, i.e. maps with maps as the value associated to a key. I tried using a nested map for funsies, and it didn’t throw an error. What I learned is that the function evaluates the presence of the key first. So if you pass a key that isn’t in the map, then the function checks for a default value. If you specified a default value, then that will be returned, even though the values in the map are not valid. If you pass a key that is in the map, then you’ll get the error that nested maps are not allowed. The key takeaway (<–see what I did there?) is that you shouldn’t use a nested map. Empty maps are fine, provided you specified a default value. Again, the function checks for the presence of a key before checking the values for validity or existence. Good times.

Coming up next is the lower() function.