By Sebastian Stadil —

A Practical Guide to Terraform Functions

Terraform has revolutionized Infrastructure as Code (IaC), allowing teams to define and provision infrastructure with remarkable efficiency. At the heart of Terraform's flexibility is its HashiCorp Configuration Language (HCL), which, while declarative, is significantly enhanced by a rich set of built-in functions. These functions are the key to transforming static configurations into dynamic, reusable, and maintainable infrastructure blueprints.

Understanding and leveraging these functions allows you to create more sophisticated and adaptive infrastructure, from generating resource names dynamically to complex data transformations. While Terraform functions provide immense power, managing their application across large teams and complex environments can introduce its own set of challenges. Platforms like Scalr offer enhanced visibility, governance, and collaboration features that complement Terraform's capabilities, ensuring that even the most dynamic configurations remain manageable, secure, and cost-effective.

Understanding Function Basics

Terraform functions are invoked with a straightforward syntax: FUNCTION_NAME(ARGUMENT_1, ARGUMENT_2, ...). For instance, max(5, 12, 9) returns 12.

Key aspects to remember:

  • No User-Defined Functions: Terraform only supports its built-in set.
  • Argument Expansion: Lists or tuples can be expanded into arguments using the ellipsis symbol (...). For example, if var.numbers is [10, 20, 5], min(var.numbers...) is equivalent to min(10, 20, 5).
  • Sensitive Data: If a function argument is sensitive (e.g., an input variable marked sensitive = true), the function's result will also be marked sensitive, redacting it from UI outputs.
  • Execution Timing:
    • Most functions are "pure," meaning their output depends only on their inputs, and Terraform can evaluate them at various times.
    • Functions like file() and templatefile() are evaluated early, during configuration validation, and cannot read dynamically generated files.
    • Functions like timestamp() (current time) and uuid() (random UUID) produce "unknown values" during the plan phase and are resolved during the apply phase. This can lead to persistent diffs if not handled carefully.

Numeric Functions: Crunching the Numbers

These functions perform mathematical operations, essential for calculations like instance counts, sizes, or limits.

  • abs(number): Returns the absolute value.
  • ceil(number): Rounds up to the nearest whole number.
  • floor(number): Rounds down to the nearest whole number.
  • max(n1, n2, ...): Returns the largest number.
  • min(n1, n2, ...): Returns the smallest number.
  • pow(base, exponent): Calculates base to the power of exponent.
  • parseint(string, base): Parses a string into an integer of a given base.

Code Example:

locals {
  instance_count_raw = "3.7"
  # Ensure a whole number of instances, always rounding up
  desired_instances  = ceil(tonumber(local.instance_count_raw)) // Result: 4

  # Determine the maximum disk size from multiple inputs
  disk_options       = [60, 100, var.custom_disk_size]
  max_disk_size      = max(local.disk_options...)

  # Parse a hexadecimal instance ID suffix to an integer
  id_suffix_hex      = "A1"
  id_suffix_int      = parseint(local.id_suffix_hex, 16) // Result: 161
}

variable "custom_disk_size" {
  type    = number
  default = 80
}

String Functions: Mastering Text Manipulation

String functions are vital for dynamically generating names, tags, formatting outputs, and preparing string data.

  • format(spec, values...): Creates a formatted string (like printf).
  • join(separator, list): Joins list elements with a separator.
  • split(separator, string): Splits a string into a list.
  • lower(string) / upper(string) / title(string): Case conversions.
  • substr(string, offset, length): Extracts a substring.
  • replace(string, search, replace): Replaces substrings (can use regex).
  • trimspace(string): Removes leading/trailing whitespace.
  • startswith(string, prefix) / endswith(string, suffix): Checks for prefix/suffix.

Code Example:

locals {
  environment = "staging"
  app_name    = "MyApplication"

  # Generate a standardized resource name
  resource_name = lower(format("%s-%s-instance", local.app_name, local.environment))
  # Result: "myapplication-staging-instance"

  # Create a comma-separated list of tags
  tag_list    = ["owner:team-alpha", "project:bluebird"]
  tags_string = join(";", local.tag_list)
  # Result: "owner:team-alpha;project:bluebird"

  # Extract the project code from a prefixed string
  project_identifier = "PROJ-WebApp"
  project_code       = replace(local.project_identifier, "/PROJ-/", "") // Result: "WebApp"
}

Collection Functions: Working with Lists, Maps, and Sets

These functions manipulate complex data structures, crucial for iterating with for_each or generating derived collections.

  • length(collection): Returns the number of elements.
  • element(list, index): Retrieves an element (wraps around).
  • concat(list1, list2, ...): Combines lists.
  • flatten(list_of_lists): Creates a single flat list from nested lists.
  • keys(map): Returns a sorted list of map keys.
  • values(map): Returns a list of map values (sorted by keys).
  • lookup(map, key, default): Safely retrieves a map value.
  • merge(map1, map2, ...): Merges maps (later maps override earlier ones).
  • toset(list) / tolist(set_or_tuple) / tomap(object): Type conversions for collections.
  • setproduct(set1, set2, ...): Computes the Cartesian product, useful for all combinations.

Code Example:

locals {
  availability_zones = ["us-west-2a", "us-west-2b", "us-west-2c"]
  # Cycle through AZs for multiple resources
  # instance_az = element(local.availability_zones, count.index) # In a resource block

  default_config = {
    cpus    = 2
    memory  = "4GB"
    storage = "50GB"
  }
  override_config = {
    memory  = "8GB" // This will override the default
    network = "high-performance"
  }
  # Merge default and override configurations
  final_config = merge(local.default_config, local.override_config)
  # Result: { cpus=2, memory="8GB", storage="50GB", network="high-performance" }

  # Get all keys from the final_config map
  config_keys = keys(local.final_config) // Result: ["cpus", "memory", "network", "storage"] (sorted)

  # Create a flat list of all security group rules from different sources
  default_rules = [{ port = 22, protocol = "tcp"}]
  app_rules     = [{ port = 80, protocol = "tcp" }, { port = 443, protocol = "tcp" }]
  all_rules     = flatten([local.default_rules, local.app_rules])
}

Encoding Functions: Bridging Data Formats

Essential for converting data between HCL and standard formats like JSON, YAML, or Base64, often for API interactions or embedding structured data.

  • jsonencode(value): Encodes a Terraform value to a JSON string.
  • jsondecode(string): Parses a JSON string to a Terraform value.
  • yamlencode(value): Encodes to a YAML string.
  • yamldecode(string): Parses a YAML string.
  • base64encode(string): Base64 encodes a string (UTF-8 assumed).
  • base64decode(string): Decodes a Base64 string (UTF-8 assumed).
  • base64gzip(string): Gzips then Base64 encodes a string.

Code Example:

locals {
  user_data_script = <<-EOT
    #!/bin/bash
    apt-get update
    apt-get install -y nginx
    echo "Instance provisioned by Terraform at $(date)" > /var/www/html/index.html
  EOT
  # Encode user data for cloud instance provisioning
  encoded_user_data = base64encode(local.user_data_script)

  # Define an IAM policy as a Terraform map and encode to JSON
  iam_policy = {
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "s3:ListBucket"
        Resource = "arn:aws:s3:::my-app-bucket"
      }
    ]
  }
  iam_policy_json = jsonencode(local.iam_policy)
}

Filesystem Functions: Interacting with Local Files

These allow configurations to read files from the local disk where Terraform is executed, useful for loading scripts, templates, or external configuration data. These are generally evaluated at plan time.

  • file(path): Reads file contents as a UTF-8 string.
  • templatefile(path, vars): Renders a template file with given variables.
  • pathexpand(path): Expands a ~ (tilde) in a path to the user's home directory.
  • fileexists(path): Checks if a regular file exists.
  • filebase64(path): Reads file contents and returns them as Base64 (for binary files).

Code Example (template user_data.tftpl):

// user_data.tftpl:
// #!/bin/bash
// echo "Welcome to ${server_role} server!"
// echo "Application version: ${app_version}" > /etc/app_version

locals {
  # Render a user data script from a template
  rendered_script = templatefile("${path.module}/user_data.tftpl", {
    server_role = "web-server"
    app_version = var.application_version
  })

  # Read an SSH public key
  ssh_public_key = trimspace(file(pathexpand("~/.ssh/id_rsa.pub")))
}

variable "application_version" {
  type    = string
  default = "1.0.0"
}

Date and Time Functions: Managing Temporal Data

Used for timestamping, scheduling, or formatting dates and times.

  • timestamp(): Returns current UTC timestamp (RFC 3339). Evaluated at apply time.
  • plantimestamp(): Returns UTC timestamp of the plan operation (Terraform v1.5+).
  • formatdate(spec, timestamp): Formats an RFC 3339 timestamp.
  • timeadd(timestamp, duration): Adds a duration (e.g., "1h", "30m") to a timestamp.

Code Example:

locals {
  # Timestamp for when the apply operation started
  apply_start_time = timestamp()

  # Format the current timestamp for a tag
  build_tag = formatdate("YYYYMMDD-hhmmss", timestamp()) # e.g., "20250522-005500"

  # Calculate a resource expiry date (e.g., 7 days from apply)
  resource_expiry_date = timeadd(timestamp(), "${7*24}h") # "168h"
}

Hash and Crypto Functions: Ensuring Integrity and Uniqueness

These functions generate hashes, UUIDs, or perform limited cryptographic operations.

  • md5(string) / sha1(string) / sha256(string) / sha512(string): Compute hashes of strings.
  • filemd5(path) / filesha1(path) / filesha256(path) / filesha512(path): Compute hashes of file contents.
  • uuid(): Generates a random (version 4 like) UUID. Evaluated at apply time, causes diffs.
  • uuidv5(namespace, name): Generates a deterministic (version 5) UUID.
  • bcrypt(string, cost): Hashes a string using bcrypt (for passwords).
  • rsadecrypt(ciphertext, privatekey): Decrypts RSA-encrypted data.

Code Example:

locals {
  # Create a unique but stable identifier for a resource based on its name
  stable_resource_id = uuidv5("dns", "my-service.example.com")

  # Generate a hash of a script to detect changes
  script_content   = file("${path.module}/configure.sh")
  script_hash      = sha256(local.script_content)
}

# Example: Use file hash to trigger S3 object updates only when content changes
resource "aws_s3_object" "script" {
  bucket = var.my_bucket_name
  key    = "scripts/configure.sh"
  source = "${path.module}/configure.sh" # Path to the local file
  etag   = filemd5("${path.module}/configure.sh")
}

variable "my_bucket_name" {
  type = string
}

(Ensure configure.sh exists in the same directory for this example)

IP Network Functions: Automating Network Configurations

Crucial for calculating IP addresses, subnets, and other network parameters.

  • cidrhost(prefix, hostnum): Calculates a host IP within a CIDR prefix.
  • cidrsubnet(prefix, newbits, netnum): Calculates a subnet CIDR from a parent.
  • cidrnetmask(prefix): Converts an IPv4 CIDR prefix to a netmask.
  • cidrsubnets(prefix, newbits...): Calculates a list of consecutive subnets.

Code Example:

locals {
  vpc_cidr_block = "10.100.0.0/16"

  # Calculate the first /24 subnet
  subnet_1_cidr = cidrsubnet(local.vpc_cidr_block, 8, 0) // Result: "10.100.0.0/24"

  # Get the 10th usable IP address in that subnet
  host_ip_in_subnet_1 = cidrhost(local.subnet_1_cidr, 10) // Result: "10.100.0.10"

  # Get the netmask for the subnet
  subnet_1_netmask = cidrnetmask(local.subnet_1_cidr) // Result: "255.255.255.0"

  # Generate a list of three /20 subnets from the VPC CIDR
  app_subnets = cidrsubnets(local.vpc_cidr_block, 4, 4, 4)
  # Result: ["10.100.0.0/20", "10.100.16.0/20", "10.100.32.0/20"]
}

Type Conversion Functions: Ensuring Data Compatibility

Explicitly convert values between Terraform types.

  • tobool(value): Converts to boolean (strict: "true", "false", true, false, null).
  • tolist(value): Converts a set or tuple to a list.
  • tomap(value): Converts an object to a map.
  • tonumber(value): Converts to a number.
  • toset(value): Converts a list or tuple to a set (removes duplicates).
  • tostring(value): Converts a primitive type to a string.
  • try(expr1, expr2, ...): Returns the result of the first successful expression.
  • can(expression): Returns true if an expression evaluates without dynamic errors.

Code Example:

locals {
  enable_feature_str = "true"
  # Convert string "true" to a boolean
  enable_feature_bool = tobool(local.enable_feature_str) // Result: true

  # Try to access an optional attribute, fallback to a default list
  optional_security_groups = try(var.custom_security_groups, [])

  # Check if a deeply nested optional attribute can be accessed
  is_monitoring_enabled = can(var.monitoring_config.advanced.metrics_port) && var.monitoring_config.advanced.metrics_port != null

  # Convert a numeric input (possibly string) to a number
  cpu_count_input = "4"
  cpu_count       = tonumber(local.cpu_count_input) // Result: 4
}

variable "custom_security_groups" {
  type    = list(string)
  default = null
}

variable "monitoring_config" {
  type    = any
  default = {}
}

Terraform-Specific Functions & Values: Context is Key

These provide information about the Terraform execution environment or allow control over data sensitivity.

  • path.module: Filesystem path of the current module.
  • path.root: Filesystem path of the root module.
  • path.cwd: Original working directory where Terraform was invoked.
  • terraform.workspace: Name of the currently selected workspace.
  • sensitive(value): Marks a value as sensitive.
  • nonsensitive(value): Removes sensitive marking (use with extreme caution).
  • issensitive(value): Checks if a value is sensitive (Terraform v1.8+).

Code Example:

locals {
  # Load configuration specific to the current workspace
  workspace_config_file = "${path.module}/configs/${terraform.workspace}.json"
  config_content        = fileexists(local.workspace_config_file) ? file(local.workspace_config_file) : "{}"

  # Mark a retrieved API key as sensitive
  retrieved_api_key = "example_super_secret_key" # In reality, this might come from a data source or file
  secure_api_key    = sensitive(local.retrieved_api_key)
}

# Output a non-sensitive part of a sensitive object (use carefully!)
output "api_key_id" {
  # Assume secure_api_key is an object like { id = "non-sensitive-id", key = "sensitive-part" }
  # This is a hypothetical example; structure your data accordingly.
  # value = nonsensitive(local.secure_api_key.id)
  value = "Example: Extract