Terraform Lookup Function – Usage And Examples

The Terraform lookup() function provides a powerful feature that can be used to implement more flexible and easily configurable infrastructure configurations. The lookup() function is essential for retrieving values from maps dynamically. This article explains Terraform maps, in case you’re not familiar yet, and the explores the Terraform lookup() function with usage examples and a few usage best practices.

Let’s dig in!

What is a Terraform Map?

In Terraform, a map is essentially a collection of key-value pairs. Maps are highly useful for managing configurations, allowing you to create more flexible and scalable infrastructure definitions.

Here’s a simple example of a variable with a map of strings in a Terraform configuration file:

variable "environment" {
  type = map(string)
  default = {
    dev  = "Development"
    prod = "Production"
    test = "Testing"
  }
}

In this example, the environment variable is a map with keys (dev, prod, test) and their respective string values (Development, Production, Testing).

Some other common uses for maps in Terraform are for helping configure groups of values for resources like virtual machines, network subnets, and more. The examples uses this article should help give you a better idea of when and how to use the lookup() function in your own Terraform configurations.

What is the Terraform Lookup Function?

The lookup() function in Terraform is an indispensable tool for dynamically retrieving values from maps, making your infrastructure configurations more flexible and resilient.

The standard way of looking up, or retrieving, the value from a map in Terraform is to use the maps dot-separator attribute notation or square-bracket index notation to retrieve the value.

Here’s an example of these:

variable "location" {
  type = map(string)
  default = {
    primary = "East US"
  }
}
# Using square-bracket dot-separated attribute notation
output "primary_location" {
  value = var.location["primary"]
}
# Using Index notation
output "secondary_location" {
  value = var.location["secondary"]
}

However, with both these notations, if the key doesn’t exist, then you will get an error. In this example, the "secondary" key doens’t exist, so that one will generate an error.

With the lookup() function, you are able to define a default value to use if they key does not exist in the map. This enables you to handle missing map keys gracefully. It can also help with implementing Convention over Configuration IaC practices in your configurations.

The lookup() function retrieves a value from a map given a specific key. If the key does not exist in the map, the function returns a default value provided by the user. This makes it an essential tool for handling optional or missing configuration values gracefully.

The basic syntax of the lookup() function is:

lookup(map, key, default)

• map: The map from which to retrieve the value.
• key: The key for which to look up the value.
• default: The default value to return if the key is not found in the map.

Terraform Lookup Function Examples

Below are some example usages of the Terraform lookup() function. Each example is illustrates slightly different usages of the function and provides you samples that you can adapt to your own Terraform configurations.

Terraform Lookup with a Map

Using the lookup() function with a basic map is straightforward.

variable "location" {
  type = map(string)
  default = {
    eastus  = "East US"
    westus  = "West US"
    central = "Central US"
  }
}

output "selected_location" {
  value = lookup(var.location, "eastus", "North Central US")
}

The output looks like this:

selected_location = "East US"

In this example, we define a map variable location that contains Azure regions as keys and their descriptions as values. The lookup() function is then used to retrieve the value associated with the key eastus. If the key does not exist, the function returns the default value "North Central US". This approach ensures that your Terraform configuration can handle missing keys gracefully without causing errors.

Here’s an example of using lookup() to reference a key does not exist:

output "selected_location" {
  value = lookup(var.location, "northcentralus", "North Central US")
}

Since the key northcentralus does not exist, it returns the "North Central US" default value.

Terraform Lookup with an Empty Map

Here, the empty_map is defined without any key-value pairs. Handling empty maps is another case that’s commonly encountered:

variable "empty_map" {
  type = map(string)
  default = {}
}

output "default_value" {
  value = lookup(var.empty_map, "nonexistent_key", "Default Value")
}

The output looks like this:

default_value = "Default Value"

In this example, the empty_map variable is defined without any key-value pairs. When the lookup() function is called with a key that does not exist ("nonexistent_key"), it returns the specified default value ("Default Value"). This is particularly useful when dealing with dynamic configurations where some maps might not have all the expected keys at all times.

Terraform Lookup with Nested Map

Using the lookup() function with nested maps adds a layer of complexity but also provides more detailed control over your configurations:

variable "nested_map" {
  type = map(map(string))
  default = {
    prod = {
      region = "East US"
      tier   = "Production"
    }
    dev = {
      region = "West US"
      tier   = "Development"
    }
  }
}

output "nested_lookup" {
  value = lookup(var.nested_map["prod"], "region", "Default Region")
}

The output looks like this:

nested_lookup = "East US"

In this example, we define a nested_map where each key (e.g., prod, dev) maps to another map containing specific configuration details. The lookup() function retrieves the region key from the prod map.

If the region key is not found, it will return the "Default Region" default value. This method is can be useful for managing environment-specific configurations within the same Terraform configuration.

Terraform Feature Flags: Another useful way to implement the lookup() function is when Feature Flags are implemented in a Terraform project. The lookup() enables the configuration of default values if certain configurable values aren’t specified.

Best Practices with Terraform Lookup

Here are some best practices to keep in mind when using the lookup() function:

1. Validate Keys and Data Types: Always ensure the keys and data types match expected values to prevent runtime errors.
2. Use Default Values Judiciously: Default values should be logical fallbacks and not mask potential configuration issues.
3. Keep Configurations Simple: Avoid overly complex lookups. Simple and readable code is easier to maintain and troubleshoot.
4. Regularly Update and Test Maps: Ensure that maps reflect the current state of your resources by regularly updating and testing them.
5. Convention over Configuration: Using the lookup() function can help implement Convention over Configuration IaC practices, helping guide the default behavior of the Terraform project when configurations aren’t present.

Summary

The lookup() function is a great tool for writing more flexible and configurable Terraform. This allows for more robust IaC code to be written when managing infrastructure. Whether dealing with simple maps, empty maps, or nested maps, understanding and utilizing lookup() effectively can significantly enhance your Terraform scripts. Also, by following best practices, you can ensure your infrastructure as code remains reliable and maintainable.

Original Article Source: Terraform Lookup Function – Usage and Examples by Chris Pietschmann (If you’re reading this somewhere other than Build5Nines.com, it was republished without permission.)