Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท The HCL Language

Terraform Built-in Functions

A practical tour of Terraform's built-in functions: strings, numbers, collections, encoding, filesystem, IP networking and type functions, including try, coalesce and templatefile.

Terraform ships with about a hundred built-in functions for transforming values inside expressions. You call them like upper("web") or merge(a, b). There are no user-defined functions in HCL, and you cannot install function libraries (providers may add a few "provider-defined functions" in recent versions), so knowing the built-ins well is part of fluency. You do not have to memorize them; learn the families and look up the rest in the reference.

The hcl code is read-only. The Python stand-ins re-implement the most useful functions so you can see inputs and outputs. In a real project, test any function with terraform console:

TEXT
> upper("terraform")
"TERRAFORM"
> cidrsubnet("10.0.0.0/16", 8, 2)
"10.0.2.0/24"

(Example console session.)

String functions

Function Example Result
upper, lower, title lower("Web-1") "web-1"
format format("%s-%03d", "web", 7) "web-007"
join join(",", ["a","b"]) "a,b"
split split(",", "a,b") ["a","b"]
replace replace("a.b", ".", "-") "a-b"
trimspace, trim, trimprefix, trimsuffix trimsuffix("a.tf", ".tf") "a"
substr substr("terraform", 0, 4) "terr"
regex, regexall regex("[0-9]+", "web42") "42"
startswith, endswith, strcontains startswith("prod-db","prod") true

format follows C-style verbs (%s, %d, %03d, %.2f, %v). Because Terraform errors on invalid values rather than guessing, use regex in validation blocks (next chapter) with can(regex(...)).

Number functions

min, max, abs, ceil, floor, pow, signum, parseint and log. They accept numbers or, for min and max, a list expanded with ...:

HCL
locals {
  replicas = max(2, ceil(var.expected_rps / 100))
  biggest  = max(var.sizes...)          # expand a list into arguments
}

Collection functions

These are the workhorses of real configurations.

Function What it does Example
length size of list, map, set or string length(var.zones)
element(list, i) item at index, wrapping around element(["a","b"], 3) is "b"
concat join lists concat(["a"], ["b"])
merge combine maps/objects; later wins merge(local.base, var.extra)
lookup(map, key, default) safe map read lookup(local.sizes, var.env, "small")
keys, values map to lists keys({a=1}) is ["a"]
flatten collapse nested lists flatten([[1],[2,3]])
distinct remove duplicates distinct(["a","a"])
contains membership test contains(["a","b"], "a")
slice, reverse, sort list helpers slice(["a","b","c"], 0, 2)
zipmap two lists to a map zipmap(["a","b"], [1,2])
setunion, setintersection, setsubtract set algebra
compact drop empty strings compact(["a","","b"])
one list of 0 or 1 items to value or null one(aws_eip.web[*].id)
toset, tolist, tomap conversions see types

merge is the standard way to combine default tags with per-resource tags:

HCL
tags = merge(local.common_tags, { Name = "web-${count.index}" })
Python Collection and string functions (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Encoding and hashing

jsonencode/jsondecode convert between values and JSON strings (essential for IAM policies), yamlencode/yamldecode do the same for YAML, base64encode/base64decode handle Base64, and md5, sha256, filesha256 and bcrypt hash data. A typical use of jsonencode:

HCL
resource "aws_iam_policy" "read" {
  name   = "read-logs"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = ["s3:GetObject"]
      Resource = ["${aws_s3_bucket.logs.arn}/*"]
    }]
  })
}

HCL objects are far easier to write and indent than embedded JSON strings, and Terraform produces valid JSON for you.

Filesystem and templates

  • file("path") reads a file's text (e.g. an SSH public key).
  • filebase64, filemd5, filesha256: read plus encode/hash.
  • fileexists, fileset(path, "*.json") check and list files.
  • templatefile("script.sh.tftpl", { port = 8080 }) renders a template file with variables, using the same ${} and %{} syntax from Expressions.
  • abspath, dirname, basename, pathexpand handle paths. Prefer "${path.module}/file" so paths work no matter where Terraform runs.
HCL
resource "aws_instance" "web" {
  user_data = templatefile("${path.module}/user-data.sh.tftpl", {
    port        = var.port
    environment = var.environment
  })
}

IP network functions

cidrsubnet, cidrhost, cidrnetmask and cidrsubnets calculate addresses so you never hand-edit CIDR blocks:

HCL
locals {
  vpc_cidr = "10.0.0.0/16"
  subnets  = [for i in range(3) : cidrsubnet(local.vpc_cidr, 8, i)]
  # ["10.0.0.0/24", "10.0.1.0/24", "10.0.2.0/24"]
}

cidrsubnet(prefix, newbits, netnum) adds newbits bits to the prefix length (here /16 to /24) and picks the netnum-th network. range(3) yields [0, 1, 2].

Python cidrsubnet and cidrhost (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Type conversion and error-handling functions

  • try(expr1, expr2, ...) returns the first expression that evaluates without error. try(var.config.port, 80) supplies a default when the attribute is missing.
  • can(expr) returns true if the expression evaluates without error; perfect for validation: can(regex("^[a-z]+$", var.name)).
  • coalesce(a, b, ...) returns the first argument that is neither null nor an empty string; coalescelist does it for lists.
  • nonsensitive, sensitive toggle the sensitivity flag (see sensitive values).
  • type conversion functions: tostring, tonumber, tobool, tolist, toset, tomap.
Python try, can and coalesce (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Date, time and misc functions

timestamp() returns the current time (and makes plans change on every run, so avoid it in resource arguments), timeadd, formatdate format and shift time, and uuid() produces a random id. These are impure: their results differ each run. Prefer the time or random providers for values that must stay fixed after creation.

Do not memorize function lists. Remember the families (string, number, collection, encoding, filesystem, network, type) and use terraform console to try inputs. When two functions look alike, the console will show the difference immediately.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does merge({ a = 1, b = 2 }, { b = 3 }) return?

    merge combines maps and later arguments override earlier ones for duplicate keys.
  2. 2. Which function returns a default when an attribute might be missing?

    try returns the first expression that evaluates without error.
  3. 3. What does cidrsubnet("10.0.0.0/16", 8, 2) return?

    Adding 8 bits turns /16 into /24, and netnum 2 selects the third network: 10.0.2.0/24.
  4. 4. Why should you avoid timestamp() inside resource arguments?

    timestamp() is impure. Using it makes each plan differ; store a time once with the time provider instead.

Summary

  • Terraform has roughly a hundred built-in functions and no user-defined ones.
  • Families: string (format, join, split, replace), number, collection (merge, lookup, flatten, zipmap), encoding (jsonencode), filesystem (file, templatefile), network (cidrsubnet) and type/error handling (try, can, coalesce).
  • merge combines tag maps, lookup gives safe defaults, templatefile renders scripts, jsonencode builds policies.
  • Impure functions (timestamp, uuid) make plans unstable.
  • Experiment in terraform console.

Next: Providers and Version Constraints