Terraform Functions And Expressions Explained

Posted on by

Functions in HashiCorp Terraform are integral to making your configurations flexible, efficient, and maintainable. They are pre-defined operations that can be used within expressions to transform and combine values. These functions can manipulate strings, perform mathematical calculations, and handle complex data structures like maps and lists, among other tasks. These functions can also be combined with expressions. Doing so allows you to dynamically define the value of resource properties at the time of deployment.

By leveraging functions, you can create more dynamic and powerful configurations, making your infrastructure as code (IaC) practices more robust and scalable.

The Role of Functions in Terraform

At its core, HashiCorp Terraform is a declarative language designed to describe and manage infrastructure. However, simply declaring resources with hard coded property values isn’t always sufficient. Real-world scenarios often demand dynamic configurations based on variable input, conditional logic, and iterative processes. This is where functions come into play.

Functions enable you to:

  • Manipulate Data: Transform data into the required format or structure.
  • Perform Calculations: Carry out arithmetic operations and logical comparisons.
  • Build Complex Structures: Assemble intricate data structures from simpler components.

For example, the merge function allows you to combine multiple maps into one. This is particularly useful when managing tags or other key-value pairs in your infrastructure configurations. Similarly, the join function can concatenate a list of strings, enabling you to dynamically build resource names or other identifiers.

Categories of Functions

Terraform functions are organized into various categories based on the type of operations they perform. This categorization helps in understanding their specific uses. It also shows how they can be combined to solve different problems in infrastructure management. Each category addresses a distinct aspect of data manipulation, ranging from basic string handling to complex data structure transformations. In this section, we’ll look at the primary categories of functions available in Terraform. Below you will find examples and insights into the practical usage of these functions. By familiarizing yourself with these categories, you will gain a comprehensive understanding of how to utilize Terraform functions. You will learn to effectively streamline your infrastructure as code practices.

Here’s an overview of the primary categories:

Numeric Functions

Numeric functions in Terraform are essential for performing mathematical operations and manipulating numerical data in your configurations. These functions allow you to ensure values are within expected ranges, perform calculations, and handle various numerical scenarios efficiently. Here, we’ll cover some of the most commonly used numeric functions, each illustrated with a concise example.

  1. Absolute Value: abs() – Returns the absolute value of a number.
  2. Ceiling: ceil() – Rounds a number up to the nearest whole number.
  3. Floor: floor() – Rounds a number down to the nearest whole number.
  4. Maximum Value: max() – Returns the largest number from a set.
  5. Minimum Value: min() – Returns the smallest number from a set.
  6. Exponentiation: pow() – Raises a number to the power of another number.
  7. Signum: signum() – Determines the sign of a number.

Let’s combine these functions into a single example to show their usage:

locals {
  # Example values
  original_value   = -42.5
  cpu_allocation   = 3.7
  desired_memory   = 7.9
  min_instance_size = 2
  requested_instance_size = 4
  max_replicas = 10
  requested_replicas = 15
  base = 2
  exponent = 3
  change_rate = -5

  # Using functions
  positive_value   = abs(local.original_value)
  rounded_cpu      = ceil(local.cpu_allocation)
  floored_memory   = floor(local.desired_memory)
  instance_size    = max(local.min_instance_size, local.requested_instance_size)
  replicas         = min(local.max_replicas, local.requested_replicas)
  exponential_value = pow(local.base, local.exponent)
  direction        = signum(local.change_rate)
}

output "numeric_functions_demo" {
  value = {
    positive_value     = local.positive_value
    rounded_cpu        = local.rounded_cpu
    floored_memory     = local.floored_memory
    instance_size      = local.instance_size
    replicas           = local.replicas
    exponential_value  = local.exponential_value
    direction          = local.direction
  }
}

This example showcases how various numeric functions can be applied to manage and transform data within your Terraform configurations. By understanding and utilizing these functions, you can create more dynamic, precise, and efficient infrastructure setups.

String Functions

String functions in Terraform are powerful tools for manipulating and formatting text within your configurations. These functions allow you to clean up strings, concatenate them, and transform them as needed to create more dynamic and readable setups. Below, we’ll explore some of the most commonly used string functions with a combined example to demonstrate their utility.

  1. Trim Whitespace: trimspace() – Removes leading and trailing whitespace from a string.
  2. Join: join() – Concatenates a list of strings into a single string with a specified separator.
  3. Split: split() – Splits a string into a list of substrings based on a specified delimiter.
  4. Lowercase: lower() – Converts a string to all lowercase characters.
  5. Uppercase: upper() – Converts a string to all uppercase characters.

Let’s combine these functions into a single example to illustrate how they can be used together:

locals {
  # Example values
  raw_string        = "   Hello, Terraform!   "
  string_list       = ["apple", "banana", "cherry"]
  delimiter         = ","
  mixed_case_string = "Terraform IS Awesome"

  # Using functions
  clean_string      = trimspace(local.raw_string)
  combined_string   = join("-", local.string_list)
  split_strings     = split(local.delimiter, "apple,banana,cherry")
  lower_case        = lower(local.mixed_case_string)
  upper_case        = upper(local.mixed_case_string)
}

output "string_functions_demo" {
  value = {
    clean_string     = local.clean_string
    combined_string  = local.combined_string
    split_strings    = local.split_strings
    lower_case       = local.lower_case
    upper_case       = local.upper_case
  }
}

In this example:

  • trimspace() removes the extra spaces around the greeting.
  • join() combines a list of fruits into a single string separated by hyphens.
  • split() breaks a comma-separated string into a list of individual strings.
  • lower() converts a mixed case string to all lowercase letters.
  • upper() converts the same string to all uppercase letters.

These functions demonstrate the versatility of Terraform’s string manipulation capabilities. They allow you to handle and format text in various useful ways within your infrastructure configurations.

Collection Functions

Collection functions in Terraform are designed to help you manipulate and manage lists and maps. They make it easier to work with complex data structures in your configurations. These functions allow you to count elements, retrieve specific items, merge maps, and more. Below, we highlight some of the most useful collection functions with a combined example to showcase their practical applications.

  1. Length: length() – Returns the number of elements in a list or keys in a map.
  2. Element: element() – Retrieves a single element from a list by its index.
  3. Flatten: flatten() – Collapses a multi-dimensional list into a single-dimensional list.
  4. Merge: merge() – Combines multiple maps into a single map.
  5. Keys: keys() – Retrieves a list of all keys from a map.
  6. Values: values() – Retrieves a list of all values from a map.

Let’s combine these functions into a single example to illustrate how they can be used together:

locals {
  # Example values
  nested_list = [["env:production", "app:web"], ["tier:frontend", "region:us-east-2"]]
  map1 = {
    a = 1
    b = 2
  }
  map2 = {
    c = 3
    d = 4
  }
  key_value_map = {
    name = "example"
    type = "demo"
  }

  # Using functions
  flattened_list = flatten(local.nested_list)
  merged_map = merge(local.map1, local.map2)
  map_keys = keys(local.key_value_map)
  map_values = values(local.key_value_map)
}

output "collection_functions_demo" {
  value = {
    flattened_list = local.flattened_list
    merged_map     = local.merged_map
    map_keys       = local.map_keys
    map_values     = local.map_values
  }
}

In this example:

  • flatten() transforms a nested list into a single list.
  • merge() combines two maps into one.
  • keys() extracts all keys from a map.
  • values() extracts all values from a map.

These functions demonstrate the power of Terraform’s collection manipulation capabilities. They allow you to efficiently manage and transform complex data structures within your configurations.

Encoding Functions

Encoding functions in Terraform are essential for converting data to and from formats like JSON and YAML. These functions enable seamless integration with various systems and APIs. These functions help in serializing complex data structures and ensuring compatibility with other tools and services. Below, we provide an overview of the key encoding functions and a combined example to illustrate their practical use.

  1. JSON Encode: jsonencode() – Converts a Terraform expression into a JSON string.
  2. JSON Decode: jsondecode() – Parses a JSON string into a Terraform expression.
  3. YAML Encode: yamlencode() – Converts a Terraform expression into a YAML string.
  4. YAML Decode: yamldecode() – Parses a YAML string into a Terraform expression.

Let’s combine these functions into a single example to illustrate their utility:

locals {
  # Example data structures
  data_map = {
    name = "example"
    type = "demo"
    enabled = true
  }
  json_string = "{"key":"value"}"
  yaml_string = "key: valuenlist:n  - item1n  - item2"

  # Using functions
  encoded_json = jsonencode(local.data_map)
  decoded_json = jsondecode(local.json_string)
  encoded_yaml = yamlencode(local.data_map)
  decoded_yaml = yamldecode(local.yaml_string)
}

output "encoding_functions_demo" {
  value = {
    encoded_json = local.encoded_json
    decoded_json = local.decoded_json
    encoded_yaml = local.encoded_yaml
    decoded_yaml = local.decoded_yaml
  }
}

In this example:

  • jsonencode() converts a map to a JSON string.
  • jsondecode() parses a JSON string back into a map.
  • yamlencode() converts a map to a YAML string.
  • yamldecode() parses a YAML string back into a map.

These functions showcase the versatility of Terraform’s encoding capabilities. They enable you to work seamlessly with different data formats. This ensures your configurations are compatible with various systems and tools.

Filesystem Functions

Filesystem functions in Terraform are essential for reading the contents of files and templates. They enable you to incorporate external data into your configurations. These functions allow you to dynamically include content from files and process templates with variables. Below, we’ll explore the key filesystem functions with a combined example to demonstrate their practical use.

  1. File: file() – Reads the contents of a file as a string.
  2. Template File: templatefile() – Reads a template file and substitutes variables within it.

Let’s combine these functions into a single example to illustrate their utility:

locals {
  # Example file paths
  file_path = "path/to/file.txt"
  template_path = "path/to/template.txt"

  # Example variables for the template
  vars = {
    var1 = "value1"
    var2 = "value2"
  }

  # Using functions
  file_content = file(local.file_path)
  template_content = templatefile(local.template_path, local.vars)
}

output "filesystem_functions_demo" {
  value = {
    file_content = local.file_content
    template_content = local.template_content
  }
}

In this example:

  • file() reads the content of a specified file as a string.
  • templatefile() reads a template file and substitutes specified variables within it.

These functions showcase the power of Terraform’s filesystem capabilities. They allow you to dynamically incorporate external data and templates into your configurations. This makes them more flexible and manageable.

Practical Applications of Functions

Harnessing the power of Terraform functions can significantly enhance the flexibility and efficiency of your infrastructure configurations. In this section, we will explore practical applications that demonstrate how these functions can be leveraged to solve real-world challenges.

These examples will showcase the versatility of functions in creating robust and adaptable Terraform scripts. They include constructing dynamic resource names, generating unique identifiers, and applying conditional logic. By embedding functions within expressions, you can streamline your code, reduce redundancy, and handle complex scenarios with ease.

To illustrate the practical utility of functions, let’s explore a few examples:

Combining Tags with merge()

This example demonstrates merging two maps of tags, which can then be applied to resources.

  locals {
    default_tags = {
      Environment = "production"
      ManagedBy   = "terraform"
    }
    additional_tags = {
      Team = "devops"
    }
    all_tags = merge(local.default_tags, local.additional_tags)
  }

  output "tags" {
    value = local.all_tags
  }

Trimming Strings with trimspace()

Here, the trimspace() function removes leading and trailing whitespace from a string.

  locals {
    description = trimspace("   Hello, World!   ")
  }

  output "cleaned_description" {
    value = local.description
  }

Using join() for Dynamic Naming

This example shows how to concatenate strings with a separator, useful for creating resource names.

  locals {
    name_parts = ["service", "env", "region"]
    resource_name = join("-", local.name_parts)
  }

  output "resource_name" {
    value = local.resource_name
  }

Using Functions within Expressions

Terraform expressions can become quite powerful when combined with functions, allowing for dynamic and flexible infrastructure definitions. One common task is string concatenation. It often involves combining static text with the output of various functions. This is done to create meaningful names, tags, or configurations. In this section, we’ll explore how to use functions within expressions to concatenate strings effectively.

String Concatenation with Embedded Function Calls

String concatenation in Terraform is straightforward but becomes more versatile when combined with functions.

Let’s look at an example where we dynamically construct a resource name by embedding function calls within the expression.

Constructing a Resource Name

Imagine you need to create a resource name that includes a prefix, an environment identifier, and a unique identifier derived from another function.

Here’s how you can achieve this:

Define Variables and Locals

First, define the necessary variables and local values that will be used in the concatenation.

variable "environment" {
  description = "The environment for deployment"
  type        = string
  default     = "production"
}

locals {
  prefix          = "app"
  unique_id       = substr(md5("unique-input"), 0, 6)
  environment_tag = trimspace(var.environment)
}
Construct the Resource Name

Use the format() function to concatenate the strings along with the embedded function calls.

locals {
  resource_name = format("%s-%s-%s", local.prefix, local.environment_tag, local.unique_id)
}

output "resource_name" {
  value = local.resource_name
}

In this example, the format() function is used to create a string in the desired format. The %s placeholders are replaced by the values of local.prefix, local.environment_tag, and local.unique_id.

  • local.prefix is a static string “app”.
  • local.environment_tag uses the trimspace() function to ensure there are no leading or trailing spaces in the environment variable.
  • local.unique_id is generated by taking the first six characters of the MD5 hash of the string “unique-input” using the substr() and md5() functions.

When you apply this Terraform configuration, the resource_name output will be a string like app-production-abc123, assuming the MD5 hash generates a string starting with “abc123”.

Breaking Down the Functions Used

Understanding the individual functions used in Terraform expressions is crucial for crafting efficient and dynamic configurations. Each function serves a specific purpose. It transforms input data to make it more useful for your infrastructure definitions. Let’s take a closer look at the key functions we used in our examples. We will break down how they work. We will explain why they are useful and how to apply them effectively in your Terraform configurations.

In our previous example, we used several built-in functions to create a dynamic resource name. Here, we will dissect these functions one by one to gain a deeper understanding of their roles and utilities. This knowledge will help you replicate similar patterns in your configurations. It will also inspire you to explore other functions available in Terraform.

MD5 Hash Function: md5()

The md5() function computes the MD5 hash of a given input string, producing a 32-character hexadecimal number. This function is particularly useful for generating unique identifiers based on input values. For instance, you might want to ensure that each instance or resource has a unique but reproducible name or tag.

local {
  unique_id = md5("unique-input")
}

This returns a string like 9a0364b9e99bb480dd25e1f0284c8555.

Substring Function: substr()

The substr() function extracts a substring from a given string, starting at a specified offset and extending for a given length. This function is useful for shortening strings or extracting specific segments from a larger string.

local {
  short_id = substr(md5("unique-input"), 0, 6)
}

If the MD5 hash is 9a0364b9e99bb480dd25e1f0284c8555, this will extract 9a0364.

Trim Whitespace Function: trimspace()

The trimspace() function removes any leading and trailing whitespace from a string. This function is handy when dealing with user inputs or values that might inadvertently include spaces, ensuring clean and predictable strings.

local {
  clean_env = trimspace("  production  ")
}

This will return production without the spaces.

Format Function: format()

The format() function constructs a string from a format pattern and a set of arguments. It replaces placeholders in the pattern with the corresponding arguments, similar to how printf works in many programming languages. This function is extremely versatile for building complex strings dynamically.

local {
  resource_name = format("app-%s-%s", var.environment, local.short_id)
}

Given var.environment as production and local.short_id as 9a0364, this will return app-production-9a0364.

By breaking down these functions, we see how each plays a crucial role. Each function transforms input data into useful outputs for Terraform configurations. Understanding how to effectively utilize functions like md5(), substr(), trimspace(), and format() empowers you to create more dynamic, flexible, and maintainable infrastructure as code. Each function has its place. Mastering their use will significantly enhance your Terraform skill set. This allows you to handle complex requirements with ease.

Practical Use Case: Tagging Resources

Effective resource management often hinges on the ability to categorize and organize resources in a meaningful way. Tagging is a powerful technique used to achieve this, allowing for better tracking, reporting, and automation of infrastructure components.

In Terraform, you can dynamically generate tags by leveraging functions and expressions. This ensures that your tagging strategy is consistent and adaptable to various environments and requirements. This section will illustrate how to use Terraform functions to create dynamic tags. This will enhance your ability to manage and organize resources efficiently.

Through practical examples, you’ll see how functions like format() and substr() can be used to construct meaningful tags. These resource tags provide valuable metadata for your infrastructure resources. Let’s explore how to implement dynamic tagging in your Terraform configurations to improve resource management and operational efficiency.

Here’s an example of creating a tag that includes the resource type and environment:

resource "azurerm_resource_group" "b59_main_rg" {
  name     = "E1-${var.environment}-B59-DataLake-rg"
  location = "East US"

  tags = {
    name = format("instance-%s-%s", var.environment, substr(md5("instance-id"), 0, 6))
    source = "terraform"
  }
}

In this resource block, the Name tag is dynamically generated using the environment variable. It also uses a unique identifier derived from the MD5 hash. This ensures that each instance has a unique but predictable tag.

Using functions within expressions in Terraform allows for highly dynamic and flexible configurations. By embedding function calls in string concatenation, you can create meaningful and unique identifiers. These identifiers, tags, and other configuration elements adapt to different variables and inputs.

This approach not only simplifies your Terraform code but also enhances its maintainability and readability. So, experiment with combining functions and expressions to make your infrastructure definitions more powerful and adaptable.

Conclusion

HashiCorp Terraform functions are essential tools that make your configurations flexible, efficient, and maintainable. They enable you to transform and combine values. You can manipulate strings and perform mathematical calculations. They also handle complex data structures like maps and lists. By leveraging these functions, you can create dynamic and powerful configurations. This enhances your infrastructure as code (IaC) practices to be more robust and scalable.

By mastering Terraform functions, you gain the ability to craft more efficient and adaptable infrastructure configurations. Whether you’re managing tags, generating unique identifiers, or incorporating external data, these functions improve your capability. They enable you to handle complex infrastructure needs with ease.

Incorporate these functions into your Terraform scripts to streamline your code, reduce redundancy, and improve readability and maintainability. Keep exploring and experimenting with these tools. You’ll find that they significantly enhance your ability to manage and automate your infrastructure as code.

Happy Terraforming!

Original Article Source: Terraform Functions and Expressions Explained by Chris Pietschmann (If you’re reading this somewhere other than Build5Nines.com, it was republished without permission.)