Function Expression

In Terraform, a function expression represents a call to a built-in function that the Terraform language provides. Functions allow the transformation and combination of values within your Terraform expressions. The basic syntax for a function expression in Terraform follows this structure:

<FUNCTION NAME>(<ARGUMENT 1>, <ARGUMENT 2>)

Here is the breakdown of syntax:

<FUNCTION NAME>: This is the name of the Terraform built-in function that you want to use. Terraform comes with a variety of useful functions, such as join(), concat(), length(), formatdate(), and many others.

<ARGUMENT 1>, <ARGUMENT 2>: These are the input values that the function requires. The number and type of arguments depend on the specific function in usage.

resource "null_resource" "string_joiner" {
    provisioner "local-exec" {
        command = echo '${join("-", ["foo", "bar", "baz"])}'
    }
}

Terraform will perform the following actions:
    # null_resource.string_joiner will be created
    + resource "null_resource" "string_joiner" {
        + id = (known after apply)
    }
Plan: 1 to add, 0 to change, 0 to destroy.

Enter a value: yes

null_resource.string_joiner: Creating...
null_resource.string_joiner: Provisioning with 'local-exec'...
null_resource.string_joiner: Executing: ["/bin/sh" "-c" "echo 'foo-bar-baz'"]
null_resource.string_joiner: foo-bar-baz
null_resource.string_joiner: Creation complete after 0s [id=4425172414869377883]

Here, the join() function joins the "foo", "bar", and "baz" strings into one string with the hyphen - as separator. The joined string is echoed to the console via the local-exec provisioner: "foo-bar-baz".

Expanding Function Arguments

In Terraform, If the arguments to pass to a function are available in a list or tuple value, you can expand that value into separate arguments using the expansion symbol ...

Here is a breakdown of the syntax:

<FUNCTION NAME>([<LIST/TUPLE VALUE>]...)

The following breakdown describes the syntax:

[<LIST/TUPLE VALUE>] This is the list or tuple value that you want to expand into separate arguments.

The three-period expansion symbol ... tells Terraform to take the elements of the list/tuple and use them as individual arguments to the function.

For example, let's say that you have a list of numbers and wanted to find the minimum value using the min():

resource "null_resource" "min_finder" {
    provisioner "local-exec" {
        command = "echo 'Minimum value is ${min([1,2,3]...)"
    }
}

Terraform will perform the following actions:
    # null_resource.min_finder will be created
    + resource "null_resource" "min_finder" {
        + id = (known after apply)
    }
Plan: 1 to add, 0 to change, 0 to destroy.

Enter a value: yes

null_resource.min_finder: Creating...
null_resource.min_finder: Provisioning with 'local-exec'...
null_resource.min_finder: Executing: ["/bin/sh" "-c" "Minimum value is 1"]
null_resource.min_finder: Minimum value is 1
null_resource.min_finder: Creation complete after 0s [id=4425172414869377883]

In this case, Terraform will expand the list [1,2,3] into individual arguments: min(1,2,3). The min() function will then return the minimum value which is 1.

Using Sensitive Data as Function Arguments

When working with sensitive data in Terraform, it is important to make sure the data stays confidential and is not exposed in plan. Terraform provides a way to mark sensitive data, such as input variables or outputs, as sensitive. When you use sensitive data as an argument to a Terraform function, then the result will also be marked as sensitive.

variable "sensitive_list" {
    default = 1
    sensitive = true
}
null_resource "sensitive_function" {
    provisioner "local-exec" {
        command = "echo 'Minimum value is ${var.sensitive_list...}"
    }
}

Terraform will perform the following actions:
    # null_resource.sensitive_function will be created
    + resource "null_resource" "sensitive_function" {
        + id = (known after apply)
    }
Plan: 1 to add, 0 to change, 0 to destroy.

Enter a value: yes

null_resource.sensitive_function: Creating...
null_resource.sensitive_function: Provisioning with 'local-exec'...
null_resource.sensitive_function: Executing: (output suppressed due to sensitive value in config)
null_resource.sensitive_function: (output suppressed due to sensitive value in config)
null_resource.sensitive_function: Creation complete after 0s [id=4425172414869377883]

In this example, the variable sensitive_list is defined as sensitive. If Terraform uses that sensitive variable in a function expression, Terraform automatically marks the result of that function as sensitive. Because Terraform does not show the output from a function to keep the sensitive information secret. Terraform does not reveal the actual output but instead shows this message: (output suppressed due to sensitive value in config).

When Terraform Calls Functions

Most Terraform built-in functions are "pure" functions, meaning that their return value depends only on their input arguments and not on any external state. The timing of calls to these functions is irrelevant. However, a small number of Terraform functions interact with external state, such as the file system or time. There are four special functions that interact with external state:

file and templatefile - Called during initial configuration validation, before any other actions. They can only read static files, not dynamic ones.

timestamp - Returns current system time in RFC 3339 format when called. This returns an unknown value during planning, and the actual result is determined during apply. It captures the time that Terraform starts applying the change, not the time that it planned it.

uuid - Returns a different random value each time it called. Similar to timestamp, it returns an estimate of an unknown value during planning and decides on its real value during the apply step.

Build-in Functions

Variables - Input value and Local value

Complex Data types - List, tuple

Deployment process

Feedback

Was this page helpful?

About

Contact

DevOpsResourceHub is designed to enhance your learning experience in DevOps technologies. While we strive to make our examples clear and easy to understand, and we regularly update our content to ensure accuracy, we acknowledge that occasional mistakes may occur. We encourage continuous learning and welcome feedback to help us improve.

Function Expression

Expanding Function Arguments

Using Sensitive Data as Function Arguments

When Terraform Calls Functions

Related Pages

Feedback