Terraform fot d matchkeys()

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 matchkeys() function. The example file is on GitHub here.

What is it?

Function name: matchkeys(values, keys, search_set)

Returns: Takes a list of values and a list of keys that are of the same length and a list of keys to search for. If a matching key from the search_set is found in the keys list, then the function returns the corresponding value from the value list. The return type is always a list. If no matching terms are found, an empty list is returned.

Example:

variable "value" {
  type = "list"
  default = "value"
}

variable "key" {
  type = "list"
  default = "key"
}

# Returns [value]
output "matchkey_output" {
  value = "${matchkey(var.value,var.key,list("key"))}"
}

Example file:

##############################################
# Function: matchkeys
##############################################
##############################################
# Variables
##############################################
variable "value_list" {
  type = "list"

  default = ["v1", "v2", "v3", "v4"]
}

variable "key_list" {
  type = "list"

  default = ["k1", "k2", "k3", "k4"]
}

variable "search_list" {
  type = "list"

  default = ["k1","k2"]
}

variable "map_test" {
  type = "map"

  default = {
    "k1" = "v1"
    "k2" = "v2"
    "k3" = "v3"
  }
}


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

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

#Basic query
output "1_matchkeys_output" {
  value = "${matchkeys(var.value_list,var.key_list,var.search_list)}"
}

#No match query
output "2_matchkeys_output" {
  value = "${matchkeys(var.value_list,var.key_list,list("k5"))}"
}

#Test with a map
output "3_matchkeys_output" {
  value = "${matchkeys(values(var.map_test),keys(var.map_test),var.search_list)}"
}

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

#All examples are in output
terraform apply

Why use it?

The main thing for me is the ability to search a map for multiple values and get them back as a list. There’s already a lookup function to check a map for a particular key value, but that only handles a single lookup operation. If you wanted to search multiple keys and get back multiple values, then lookup won’t do that for you. Instead you can take a map object and use the values and keys functions to get lists and drop them into the matchkeys function. I don’t have a real world example of where I would use this, but I can see the need for such a function to exist.

Lessons Learned

I had to read the doc for this function about five times before I thought I understood what it did. And the example given did not really help clear that up for me at all. That’s part of the reason I started this series of posts in the first place. Hopefully, if you are also confused by this function, this post helped clear up some of that confusion. It’s also important to note that the search set must also be a list type and not a string. If you are only looking for a single value in a map, just use the lookup function. If you have two lists, you can always use the zipmap function to create a map first, then use the lookup function.

Coming up next is the max() function.