Terraform is a popular IaC (Infrastructure as Code) tool that allows users to define infrastructure resources and provision and manage them through simple code.
Developers use a terraform configuration file to write this code in HCL (HashiCorp Configuration Language), which has a simple and easily understandable syntax. Due to this simplicity of the syntax, the number of Terraform users is increasing daily.
When considering Terraform’s features, developers are given many unique features. One of those features includes the Terraform lookup function, which becomes quite handy when working with the infrastructure resources.
In this article, we will look at the definition of the lookup function, its syntax, how it works, why we need it, and some examples of using the lookup function.
Firstly, let’s see the definition of the lookup function in Terraform.
What is the Terraform lookup function?
In Terraform, we use the lookup function to fetch,
- The value associated with a user-specified key from a map OR,
- The value associated with a user-specified index from a list.
This feature can be handy when working with dynamic configurations such as handling default values, selecting values conditionally, etc.
Now, let’s understand the syntax of the lookup function.
Syntax of the Terraform lookup function.
The syntax structure remains the same for retrieving values from both maps and lists, but the parameters differ.
For maps:
lookup(map, key, default_value)
- map: Here, we define the name of the map from which we fetch the value.
- key: Here, we describe the key to search through the map to find the value.
- default_value (Optional): If the specified key is not found, we define a default value to be provided by Terraform.
For lists:
lookup(list, index, default_value)
- list: Here, we define the list name from which we fetch the value.
- index: Here, we describe the index to search through the list to find the value.
- default_value (Optional): If the specified index is not found, we define a default value to be provided by Terraform.
Next, we discuss the behavior of this lookup function.
How the lookup function works.
After we give the relevant parameters, the lookup function searches for the specified key/index throughout the defined map/list.
- If it finds the key/index, It returns the value associated with that key or index.
- If no key/index is found, it returns the default value we specified.
- If we haven’t defined a default value, it returns null as the output.
Next, we see the need to use the lookup function in Terraform.
Why do we need the lookup function in Terraform?
In Terraform, the lookup function is a search function for maps and lists. It enables developers to review any map/list and extract a specific value for the given key/index.
For example, think you have ten Amazon EC2 instances with different AMIs. We can create a map or a list to store all the IDs of those different AMIs to maintain them as a single object.
But imagine a situation where you will need to retrieve the ID of a specific AMI. This is where the lookup function comes in handy. We can set the relevant parameters to get the particular AMI ID and a default value to be returned when there is no defined key or index in the map or list.
Let’s learn how to use the Terraform lookup function with some examples.
Example: Fetching a specific value from a map
variable "map" {
default = {
"a" = "Apple"
"b" = "Bee"
}
}Imagine you have the above ‘map’ variable defined in your main.tf file. As you can see, there are two key-value pairs, and we can access each pair by executing the below commands.
var.map["a"]
Output: "Apple"
var.map["b"]
Output: "Bee"Suppose we are searching for an index that does not exist in the map. Therefore, Terraform will display an error. But when using a lookup function, we can avoid getting errors. Instead, we can define a default value and show it whenever the developer searches for a key/index that does not exist.
Look below commands.
lookup(var.map, "a", "noKey")
Output: "Apple"
lookup(var.map, "z", "noKey")
Output: "noKey"As expected, Terraform provides us with the default value when we search for non-existing keys.
Example: Setting EC2 instance type based on the specified environment from a map
variable "env" {
description = "This variable defines the environment to be used"
default = "development"
}
variable "amis" {
type = map(string)
default = {
development = "t2.micro"
production = "t3.large"
staging = "t2.medium"
}
}
resource "aws_instance" "myec2" {
ami = "ami-59cbfaf0c55b1e1f0"
instance_type = lookup(var.amis, var.env, "t2.micro")
}Here, we will set up the instance type for an EC2 instance based on the specific environment defined in the ‘env’ variable. We have declared a map inside the ‘amis’ variable that consists of some instance types for different environments.
So, after performing the Terraform workflow (terraform init, plan, and apply), Terraform will search for the key (var.env) specified in the lookup function. In the ‘env’ variable, we have set the value as the ‘development’ so Terraform will search for the ‘development’ key inside the specified map (var.amis).
Our code has a key named ‘development’, so Terraform will use its value (‘t2.micro’) as the instance type for the EC2 instance.
Now imagine our ‘env’ variable is set as below.
variable "env" {
description = "This variable defines the environment to be used"
default = "testing"
}Now, Terraform will look for the ‘testing’ key in the map. Since the map has no key for ‘testing,’ it will use the default value (t2.micro) defined in the lookup function as the instance type for the EC2 instance.
Conclusion
In this writing, we looked at a unique feature that Terraform provides to its users: the lookup function. The lookup function is a function in Terraform that we can use to extract the value of a specified key from a map/index from a list. It uses a simple syntax for both maps and lists, and by following some quick steps, we can instantly fetch the value associated with the defined key.
There are numerous situations where we will need the lookup function, and we are responsible for utilizing these features to get the maximum benefits from Terraform.