In this article, we will take a look at the Terraform collection function, coalesce. We will explain what it is, what you might use it for, and how it compares to the similar try function, before running through a few examples of its use.
The Terraform language includes many built-in functions you can call from within expressions to transform and combine values.
The coalesce function is categorized as a ‘collection’ function — in Terraform, a collection function refers to functions that operate on collections of values, such as lists, maps, or sets. These functions are used to manipulate and transform data within your Terraform configurations.
The Terraform coalesce function takes any number of arguments and returns the first one that isn’t null or an empty string. It is useful when you need to provide defaults, set missing values, or prioritize different value sources.
Note:
- All arguments to Terraform
coalescemust be of the same type. Terraform will attempt conversions, but mismatched types can lead to errors. coalescechecks arguments one by one until it finds a non-null or non-empty string. If none are found, it returns null.coalesceisn’t a substitute for proper validation and handling of missing data. Use it strategically to make your configurations more concise and robust.
A similar function Terraform coalescelist is available that performs a similar operation with list arguments rather than individual arguments.
Terraform coalesce vs try
The Terraform try function executes a sequence of expressions and returns the first one that doesn’t produce an error. It works by trying each expression in order and returning the successful result.
Where Terraform coalesce is more suited for setting default values for optional strings, the try function’s purpose is to run expressions and handle errors. coalesce is used for simple defaults and missing attributes, where try is used where conditional logic is required and for handling failures. coalesce has no error handling abiltity.
Example 1: Setting defaults
One of the main uses for Terraform coalese is to set defaults. In the example below, the name for an AWS instance has an optional variable called user_defined_name. If it is not supplied, coalesce is used to provide a default of my-generic-instance-name.
resource "aws_instance" "my_instance" {
name = coalesce(var.user_defined_name, "my-generic-instance-name")
...
}Example 2: Providing missing values
Another useful application of the coalesce function is to provide missing values.
In the example below, we query an API, which may or may not provide a description for a record with a given name. coalesce can be used to avoid errors caused by missing attributes and ensures you still have a valid value for the resource property description.
data "external" "my_data" {
name = "some_api"
...
}
resource "my_resource" "my_resource" {
name = data.external.my_data.id
description = coalesce(data.external.my_data.description, "No description available")
...
}Example 3: Prioritizing different value sources
Lastly, coalesce can be used to prioritize different value sources. For instance, you might prefer a user-defined configuration file over environment variables.
In the example below, if config.json defines my_setting, it takes precedence. Otherwise, the environment variable is checked, and finally, the default value is used if neither is present.
config_file_value = file("config.json").my_setting
environment_value = var.environment_settings.my_setting
setting = coalesce(config_file_value, environment_value, "default_value")Example 4: Experimenting with terraform console
Don’t forget you can also fire up the terraform console to experiment with the coalesce function.
Here, “luke” is returned because it is the first one that is not null or an empty string:
Here, “darth” is returned because the first value supplied is an empty string:
Here, “darth” is returned because the first value supplied is null :
Terraform coalesce function takes any number of arguments and returns the first one that isn’t null or an empty string, making it a useful option when working with optional values and setting defaults.
We encourage you also to explore how Spacelift makes it easy to work with Terraform. If you need any help managing your Terraform infrastructure, building more complex workflows based on Terraform, and managing AWS credentials per run, instead of using a static pair on your local machine, Spacelift is a fantastic tool for this.
Note: New versions of Terraform are placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.
Manage Terraform Better with Spacelift
Build more complex workflows based on Terraform using policy as code, programmatic configuration, context sharing, drift detection, resource visualization and many more.
