mirror of
https://github.com/opentffoundation/opentf.git
synced 2025-12-21 02:37:43 -05:00
120 lines
4.4 KiB
Plaintext
120 lines
4.4 KiB
Plaintext
---
|
|
description: >-
|
|
Functions transform and combine values. Learn about OpenTofu's built-in
|
|
functions.
|
|
---
|
|
|
|
# Function Calls
|
|
|
|
The OpenTofu language has a number of
|
|
[built-in functions](../../language/functions/index.mdx) 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](../../language/functions/index.mdx).
|
|
|
|
## 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](../../language/values/variables.mdx#suppressing-values-in-cli-output)
|
|
or [an output defined](../../language/values/outputs.mdx#sensitive-suppressing-values-in-cli-output) as sensitive
|
|
as function arguments, the sensitive information in the arguments will be tracked during the function call.
|
|
|
|
For example, passing an object containing a sensitive input variable to the `keys()` function
|
|
will return a list with all keys we expected, but the `values()` function will result in
|
|
a list with first item as sensitive, because the value of key "a" is sensitive.
|
|
|
|
```shell
|
|
> local.baz
|
|
{
|
|
"a" = (sensitive value)
|
|
"b" = "dog"
|
|
}
|
|
> keys(local.baz)
|
|
[
|
|
"a",
|
|
"b",
|
|
]
|
|
> values(local.baz)
|
|
[
|
|
(sensitive value),
|
|
"dog",
|
|
]
|
|
```
|
|
|
|
## When OpenTofu Calls Functions
|
|
|
|
Most of OpenTofu'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 OpenTofu would call them.
|
|
|
|
However, a small subset of functions interact with outside state and so for
|
|
those it can be helpful to know when OpenTofu will call them in relation to
|
|
other events that occur in an OpenTofu run.
|
|
|
|
The small set of special functions includes
|
|
[`file`](../../language/functions/file.mdx),
|
|
[`templatefile`](../../language/functions/templatefile.mdx),
|
|
[`timestamp`](../../language/functions/timestamp.mdx),
|
|
and [`uuid`](../../language/functions/uuid.mdx).
|
|
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 OpenTofu 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 OpenTofu 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 OpenTofu execution model.
|
|
|
|
For that reason, OpenTofu arranges for both of those functions to produce
|
|
[unknown value](references.mdx#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 OpenTofu began applying the change, rather than when
|
|
OpenTofu _planned_ the change.
|
|
|
|
For more details on the behavior of these functions, refer to their own
|
|
documentation pages.
|