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 coalescelist() function. The example file is on GitHub here.
What is it?
Function name: coalescelist(list,list,…)
Returns: Takes two or more lists and returns the first non-empty list from the arguments. Must include at least two arguments to evaluate. Does not accept a list of lists as multiple arguments.
Example:
variable "list" {
default = ["My","list","of","stuff"]
}
variable "empty_list" {
default = []
}
# Returns ["My","list","of","stuff"]
output "coalescelist" {
value = "${coalescelist(var.empty_list,var.list)}"
}
Example file:
##############################################
# Function: coalescelist
##############################################
##############################################
# Variables
##############################################
variable "list_1" {
default = []
}
variable "list_2" {
default = [[], [], []]
}
variable "list_3" {
default = [false, false, false]
}
variable "list_4" {
default = ["So", "Long", "and", "Thanks"]
}
##############################################
# Resources
##############################################
##############################################
# Outputs
##############################################
output "coalescelist_output" {
value = "${coalescelist(var.list_1,var.list_2,var.list_3,var.list_4)}"
}
Run the following from the coalescelist folder to get example output for a number of different cases:
#Evaluate to "one", "two", "three"]
terraform apply -var-file="example1.tfvars"
#Is an list of empty lists empty? Nope, list_2 will be returned
terraform apply
#What about a list of boolean false values? Evaluates to all 0s
terraform apply -var "list_2=[]"
#All empty, evaluate to empty
terraform apply -var "list_2=[]" -var "list_3=[]" -var "list_4=[]"
Why use it?
I have to admit I was a little stumped on when you would actually use this. It seems like you would need a situation where you would check the output of multiple resources, and then be okay with selecting the first non-empty value as the value you would want to use. I am sure there is a situation for this, but I have no idea what it might be.
Lessons Learned
The function will take a list of lists as a value, but it doesn’t expand the list of lists. The function will evaluate the boolean value false in a list as an int value of 0. If you have a list of boolean false values or a list of empty lists [] those both count as values in a list. I also discovered that passing a list
of strings via the var command line argument doesn’t work so well in Windows.
terraform apply -var 'list_1=["one","two","three"]'
That command errors out for me when it tries to parse the list. So I had to create a tfvars file to test that combination. Other than that, it does precisely what it advertises. I do find the naming a little confusing, since coalesce means to combine multiple things into a single entity. But then I found that there is a Coalesce function in T-SQL that also returns the first non-null value in a list. I suppose in the world of programming, coalesce has this other established definition.
Coming up next is the compact() function.