Functions

HCL functions are a fundamental aspect of Terraform, empowering you to create dynamic and flexible infrastructure configurations. By leveraging the extensive range of built-in functions, you can manipulate data, perform calculations, iterate over collections, and make informed decisions based on conditions!

In this section we will take a look at some practical examples of a few common scenarios where HCL functions can significantly enhance your Terraform configurations!

String Manipulation

HCL functions like upper(), lower(), replace(), and substr() allow you to transform and manipulate strings easily. For instance, you can convert a string to uppercase, replace specific characters, or extract a substring.

locals {
  upper_case_str   = upper("hello world")
  lower_case_str   = lower("HELLO WORLD")
  replaced_str     = replace("hashicorp terraform", "hashicorp", "HCL")
  substring_str    = substr("terraform", 0, 4)
}

Mathematical Calculations

Functions like min(), max(), ceil(), and floor() enable you to perform mathematical operations on numeric values. You can calculate the minimum or maximum value, round numbers up or down, and much more.

locals {
  minimum_value = min(5, 10, 3)
  maximum_value = max(2, 8, 6)
  rounded_up    = ceil(5.3)
  rounded_down  = floor(7.9)
}

Iteration and Looping

HCL functions such as for and count allow you to iterate over lists or maps and perform actions on each element. You can dynamically create resources, generate variable values, or configure conditional behaviour.

resource "aws_instance" "example" {
  count = length(var.instance_types)

  instance_type = var.instance_types[count.index]
}

output "instance_types_upper" {
  value = [for i in var.instance_types : upper(i)]
}

Filesystem Functions

Terraform provides a set of filesystem functions that enable you to interact with files and directories. For instance, the file() function allows you to read the contents of a file and use it in your Terraform configuration. You can leverage this function to load configuration data from external files or pass file contents as inputs to resources.

locals {
  file_content = file("${path.module}/example.txt")
}

Date and Time Functions

HCL functions offer capabilities to work with dates, times, and durations. The timestamp() function returns the current timestamp, while formatdate() allows you to format a timestamp into a specific date or time format. You can perform date arithmetic using functions like timeadd() to calculate durations or add/subtract time from timestamps.

locals {
  current_time      = timestamp()
  formatted_time    = formatdate("YYYY-MM-DD", timestamp())
  time_after_1_hour = timeadd(timestamp(), "1h")
}

Collection Functions

Terraform provides various functions to work with lists and maps. The length() function allows you to determine the length of a list or map. You can extract specific elements from a list using element() or slice(). The keys() and values() functions help you retrieve the keys and values of a map, respectively. These functions enable you to manipulate and transform collections to fit your infrastructure requirements.

locals {
  my_list    = ["apple", "banana", "cherry"]
  list_length = length(local.my_list)
  second_element = element(local.my_list, 1)
  sliced_list = slice(local.my_list, 0, 2)

  my_map   = { "key1" = "value1", "key2" = "value2" }
  map_keys = keys(local.my_map)
  map_values = values(local.my_map)
}

Encoding and Decoding Functions

HCL functions include functions for encoding and decoding data formats like Base64. The base64encode() function allows you to encode data to Base64 format, while base64decode() decodes Base64-encoded data. These functions come in handy when working with secrets or manipulating data in specific formats.

locals {
  encoded_value   = base64encode("my-secret-value")
  decoded_value   = base64decode("bXktc2VjcmV0LXZhbHVl")
}

Experimenting with HCL Functions

A quick way to experiment with HCL functions, and more generally testing out manipulating resources, variables within a Terraform project is to use Terraform console. The console requires an initialised project, and allows testing of terraform functions and interaction with resources within the project.

terraform console

Conclusion

As you delve deeper into Terraform, take the time to explore the extensive library of built-in functions. Experiment with different functions and learn how they can be combined to solve complex problems. By understanding the functionality and potential use cases of HCL functions, you’ll be equipped to craft elegant and efficient Terraform configurations.