github.com/hugorut/terraform@v1.1.3/website/docs/language/expressions/function-calls.mdx (about)

     1  ---
     2  page_title: Function Calls - Configuration Language
     3  description: >-
     4    Functions transform and combine values. Learn about Terraform's built-in
     5    functions.
     6  ---
     7  
     8  # Function Calls
     9  
    10  > **Hands-on:** Try the [Perform Dynamic Operations with Functions](https://learn.hashicorp.com/tutorials/terraform/functions?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
    11  
    12  The Terraform language has a number of
    13  [built-in functions](/language/functions) that can be used
    14  in expressions to transform and combine values. These
    15  are similar to the operators but all follow a common syntax:
    16  
    17  ```hcl
    18  <FUNCTION NAME>(<ARGUMENT 1>, <ARGUMENT 2>)
    19  ```
    20  
    21  The function name specifies which function to call. Each defined function
    22  expects a specific number of arguments with specific value types, and returns a
    23  specific value type as a result.
    24  
    25  Some functions take an arbitrary number of arguments. For example, the `min`
    26  function takes any amount of number arguments and returns the one that is
    27  numerically smallest:
    28  
    29  ```hcl
    30  min(55, 3453, 2)
    31  ```
    32  
    33  A function call expression evaluates to the function's return value.
    34  
    35  ## Available Functions
    36  
    37  For a full list of available functions, see
    38  [the function reference](/language/functions).
    39  
    40  ## Expanding Function Arguments
    41  
    42  If the arguments to pass to a function are available in a list or tuple value,
    43  that value can be _expanded_ into separate arguments. Provide the list value as
    44  an argument and follow it with the `...` symbol:
    45  
    46  ```hcl
    47  min([55, 2453, 2]...)
    48  ```
    49  
    50  The expansion symbol is three periods (`...`), not a Unicode ellipsis character
    51  (`…`). Expansion is a special syntax that is only available in function calls.
    52  
    53  ## Using Sensitive Data as Function Arguments
    54  
    55  When using sensitive data, such as [an input variable](/language/values/variables#suppressing-values-in-cli-output)
    56  or [an output defined](/language/values/outputs#sensitive-suppressing-values-in-cli-output) as sensitive
    57  as function arguments, the result of the function call will be marked as sensitive.
    58  
    59  This is a conservative behavior that is true irrespective of the function being
    60  called. For example, passing an object containing a sensitive input variable to
    61  the `keys()` function will result in a list that is sensitive:
    62  
    63  ```shell
    64  > local.baz
    65  {
    66    "a" = (sensitive)
    67    "b" = "dog"
    68  }
    69  > keys(local.baz)
    70  (sensitive)
    71  ```
    72  
    73  ## When Terraform Calls Functions
    74  
    75  Most of Terraform's built-in functions are, in programming language terms,
    76  [pure functions](https://en.wikipedia.org/wiki/Pure_function). This means that
    77  their result is based only on their arguments and so it doesn't make any
    78  practical difference when Terraform would call them.
    79  
    80  However, a small subset of functions interact with outside state and so for
    81  those it can be helpful to know when Terraform will call them in relation to
    82  other events that occur in a Terraform run.
    83  
    84  The small set of special functions includes
    85  [`file`](/language/functions/file),
    86  [`templatefile`](/language/functions/templatefile),
    87  [`timestamp`](/language/functions/timestamp),
    88  and [`uuid`](/language/functions/uuid).
    89  If you are not working with these functions then you don't need
    90  to read this section, although the information here may still be interesting
    91  background information.
    92  
    93  The `file` and `templatefile` functions are intended for reading files that
    94  are included as a static part of the configuration and so Terraform will
    95  execute these functions as part of initial configuration validation, before
    96  taking any other actions with the configuration. That means you cannot use
    97  either function to read files that your configuration might generate
    98  dynamically on disk as part of the plan or apply steps.
    99  
   100  The `timestamp` function returns a representation of the current system time
   101  at the point when Terraform calls it, and the `uuid` function returns a random
   102  result which differs on each call. Without any special behavior, these would
   103  both cause the final configuration during the apply step not to match the
   104  actions shown in the plan, which violates the Terraform execution model.
   105  
   106  For that reason, Terraform arranges for both of those functions to produce
   107  [unknown value](/language/expressions/references#values-not-yet-known) results during the
   108  plan step, with the real result being decided only during the apply step.
   109  For `timestamp` in particular, this means that the recorded time will be
   110  the instant when Terraform began applying the change, rather than when
   111  Terraform _planned_ the change.
   112  
   113  For more details on the behavior of these functions, refer to their own
   114  documentation pages.