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.