mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-02-17 10:01:05 -05:00
113 lines
4.3 KiB
Plaintext
113 lines
4.3 KiB
Plaintext
---
|
|
page_title: Function Calls - Configuration Language
|
|
description: >-
|
|
Functions transform and combine values. Learn about OpenTF's built-in
|
|
functions.
|
|
---
|
|
|
|
# Function Calls
|
|
|
|
The OpenTF language has a number of
|
|
[built-in functions](/opentf/language/functions) that can be used
|
|
in expressions to transform and combine values. These
|
|
are similar to the operators but all follow a common syntax:
|
|
|
|
```hcl
|
|
<FUNCTION NAME>(<ARGUMENT 1>, <ARGUMENT 2>)
|
|
```
|
|
|
|
The function name specifies which function to call. Each defined function
|
|
expects a specific number of arguments with specific value types, and returns a
|
|
specific value type as a result.
|
|
|
|
Some functions take an arbitrary number of arguments. For example, the `min`
|
|
function takes any amount of number arguments and returns the one that is
|
|
numerically smallest:
|
|
|
|
```hcl
|
|
min(55, 3453, 2)
|
|
```
|
|
|
|
A function call expression evaluates to the function's return value.
|
|
|
|
## Available Functions
|
|
|
|
For a full list of available functions, see
|
|
[the function reference](/opentf/language/functions).
|
|
|
|
## Expanding Function Arguments
|
|
|
|
If the arguments to pass to a function are available in a list or tuple value,
|
|
that value can be _expanded_ into separate arguments. Provide the list value as
|
|
an argument and follow it with the `...` symbol:
|
|
|
|
```hcl
|
|
min([55, 2453, 2]...)
|
|
```
|
|
|
|
The expansion symbol is three periods (`...`), not a Unicode ellipsis character
|
|
(`…`). Expansion is a special syntax that is only available in function calls.
|
|
|
|
## Using Sensitive Data as Function Arguments
|
|
|
|
When using sensitive data, such as [an input variable](/opentf/language/values/variables#suppressing-values-in-cli-output)
|
|
or [an output defined](/opentf/language/values/outputs#sensitive-suppressing-values-in-cli-output) as sensitive
|
|
as function arguments, the result of the function call will be marked as sensitive.
|
|
|
|
This is a conservative behavior that is true irrespective of the function being
|
|
called. For example, passing an object containing a sensitive input variable to
|
|
the `keys()` function will result in a list that is sensitive:
|
|
|
|
```shell
|
|
> local.baz
|
|
{
|
|
"a" = (sensitive value)
|
|
"b" = "dog"
|
|
}
|
|
> keys(local.baz)
|
|
(sensitive value)
|
|
```
|
|
|
|
## When OpenTF Calls Functions
|
|
|
|
Most of OpenTF's built-in functions are, in programming language terms,
|
|
[pure functions](https://en.wikipedia.org/wiki/Pure_function). This means that
|
|
their result is based only on their arguments and so it doesn't make any
|
|
practical difference when OpenTF would call them.
|
|
|
|
However, a small subset of functions interact with outside state and so for
|
|
those it can be helpful to know when OpenTF will call them in relation to
|
|
other events that occur in a OpenTF run.
|
|
|
|
The small set of special functions includes
|
|
[`file`](/opentf/language/functions/file),
|
|
[`templatefile`](/opentf/language/functions/templatefile),
|
|
[`timestamp`](/opentf/language/functions/timestamp),
|
|
and [`uuid`](/opentf/language/functions/uuid).
|
|
If you are not working with these functions then you don't need
|
|
to read this section, although the information here may still be interesting
|
|
background information.
|
|
|
|
The `file` and `templatefile` functions are intended for reading files that
|
|
are included as a static part of the configuration and so OpenTF will
|
|
execute these functions as part of initial configuration validation, before
|
|
taking any other actions with the configuration. That means you cannot use
|
|
either function to read files that your configuration might generate
|
|
dynamically on disk as part of the plan or apply steps.
|
|
|
|
The `timestamp` function returns a representation of the current system time
|
|
at the point when OpenTF calls it, and the `uuid` function returns a random
|
|
result which differs on each call. Without any special behavior, these would
|
|
both cause the final configuration during the apply step not to match the
|
|
actions shown in the plan, which violates the OpenTF execution model.
|
|
|
|
For that reason, OpenTF arranges for both of those functions to produce
|
|
[unknown value](/opentf/language/expressions/references#values-not-yet-known) results during the
|
|
plan step, with the real result being decided only during the apply step.
|
|
For `timestamp` in particular, this means that the recorded time will be
|
|
the instant when OpenTF began applying the change, rather than when
|
|
OpenTF _planned_ the change.
|
|
|
|
For more details on the behavior of these functions, refer to their own
|
|
documentation pages.
|