Terraform fot d length()

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 length() function. The example file is on GitHub here.

What is it?

Function name: length(value)

Returns: Takes a value of string, list, or map and returns the number of elements in the value. For a string it is the number of characters, a list is the number of first level elements, and a map is the number of first level key-value pairs.

Example:

variable "string" {
  type = "string"

  default = "Four"
}

# Returns 4
output "length_output" {
  value = "${length(var.string)}"
}

Example file:

##############################################
# Function: length
##############################################
##############################################
# Variables
##############################################
variable "simple_value" {
  default = "Ford"
}

variable "simple_list" {
  type = "list"

  default = ["So", "long", "and", "thanks"]
}

variable "nested_list" {
  type = "list"

  default = [
    ["So"],
    ["Long"],
    ["and"],
    ["thanks!"],
  ]
}

variable "mixed_list" {
  type = "list"

  default = [
    [
      ["3-1"],
      "2-1",
    ],
    [
      ["3-2"],
      "2-2",
    ],
    "1-1",
  ]
}

variable "bool_value" {
  default = true
}

variable "map_value" {
  type = "map"

  default = {
    "life"       = "42"
    "universe"   = "6"
    "everything" = "7"
  }
}

variable "empty_map" {
  type = "map"

  default = {}
}

variable "nested_map" {
  type = "map"

  default = {
    "map_one" = {
      "key_1-1" = "value_1-1"
      "key_1-2" = "value_1-2"
    }

    "map_two" = {
      "key_2-1" = "value_2-1"
      "key_2-2" = "value_2-2"
    }
  }
}

##############################################
# Resources
##############################################

##############################################
# Outputs
##############################################

output "1_simple_value_output" {
  value = "${length(var.simple_value)}"
}

output "2_simple_list_output" {
  value = "${length(var.simple_list)}"
}

output "3_nested_list_output" {
  value = "${length(var.nested_list)}"
}

output "4_mixed_list_output" {
  value = "${length(var.mixed_list)}"
}

output "5_bool_value_output" {
  value = "${length(var.bool_value)}"
}

output "6_map_output" {
  value = "${length(var.map_value)}"
}

output "7_empty_map_output" {
  value = "${length(var.empty_map)}"
}

output "8_map_output" {
  value = "${length(var.nested_map)}"
}

Run the following from the length folder to get example output for a number of different cases:

#All examples are in variables
terraform apply

Why use it?

Length is one of those fundamental functions that you just assume will be there. There’s not a whole lot more to say about that. If you use Terraform for anything beyond the simplest of configs, you are going to end up using the length function for something. I guarantee it.

Lessons Learned

The nice thing is that there is a single function for all three primitive types. I don’t have to use lengthlist and lengthmap or something similar. Regardless of the value type being passed, you will get the appropriate count of elements. This is also a potential danger for debugging, since Terraform is not going to throw an error if the wrong type is passed. That can lead to potential unexpected behavior. Probably important to keep in mind if you are applying length to data coming from a data source or third-party module.

Coming up next is the list() function.