Terraform
Built-in Functions
Hands-on: Try the Perform Dynamic Operations with Functions tutorial.
The Terraform language includes a number of built-in functions that you can call from within expressions to transform and combine values. The general syntax for function calls is a function name followed by comma-separated arguments in parentheses:
max(5, 12, 9)
For more details on syntax, see Function Calls in the Expressions section.
Provider-defined Functions
You cannot define your own functions in the Terraform configuration language, but you can develop your own providers that expose functions. Refer to Provider-defined functions for information about defining functions in custom providers.
When using a provider-specific function, add the provider::<local-name>:: where
<local-name> corresponds with an entry in the required_providers block.
The following example calls the encode_tfvars function in the terraform provider:
provider::terraform::encode_tfvars({
example = "Hello!"
})
The documentation covers the built-in functions and built-in provider-defined functions only.
Functions defined by external providers are documented by those providers in the Terraform Registry.
Experimenting with Functions
You can experiment with the behavior of Terraform's built-in functions from
the Terraform expression console, by running
the terraform console command:
> max(5, 12, 9)
12
The examples in the documentation for each function use console output to illustrate the result of calling the function with different parameters.
Function support by configuration file type
Standard Terraform configuration files support all functions, but other configuration types, such as Terraform Stacks, only support a subset of Terraform functions in deployment and component configurations. The following tables describe function support across Terraform configuration types.
Numeric functions
| Function | Configuration type | Description |
|---|---|---|
| ceil | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | Returns the closest whole number that is greater than or equal to the given value, which may be a fraction. |
| floor | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | Returns the closest whole number that is less than or equal to the given value, which may be a fraction. |
| log | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | Returns the logarithm of a given number in a given base. |
| max | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | Returns the greatest number from a set of one or more numbers. |
| min | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | Returns the smallest number from a set of one or more numbers. |
| parseint | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | Parses a given string as a representation of an integer in the specified base and returns the resulting number. |
| pow | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | Calculates an exponent, by raising its first argument to the power of the second argument. |
| signum | .hcl | Determines the sign of a number, returning -1, 0, or -1 to represent the sign. |
String functions
| Function | Configuration type | Description |
|---|---|---|
| chomp | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | removes newline characters at the end of a string |
| endswith | .hcl | returns true if the given string ends with the given suffix, false otherwise |
| format | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | produces a string by formatting a number of other values according to a specification string |
| formatlist | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | produces a list of strings by formatting a number of other values according to a specification string |
| indent | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | adds a specified number of spaces to the beginning of each line in a multi-line string, except for the first line |
| join | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | produces a string by concatenating all of the elements of the specified list of strings with the specified separator |
| lower | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | converts all cased letters in the given string to lowercase |
| regex | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | applies a regular expression to a string and returns the matching substrings |
| regexall | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | applies a regular expression to a string and returns a list of all matches |
| replace | .hcl | searches a given string for another given substring, and replaces each occurrence with a given replacement string |
| split | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | produces a list by dividing a given string at all occurrences of a given separator |
| startswith | .hcl | returns true if the given string begins with the given prefix |
| strcontains | .hcl | returns true if the first string contains the second |
| strrev | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | reverses the characters in a string |
| substr | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | extracts a substring from a given string by offset and length |
| templatestring | .hcl | renders a string as a template using a set of variables |
| title | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | converts the first letter of each word in the given string to uppercase |
| trim | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | removes the specified set of characters from the start and end of the given string |
| trimprefix | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | removes the specified prefix from the start of the given string |
| trimsuffix | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | removes the specified suffix from the end of the given string |
| trimspace | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | removes any space characters from the start and end of the given string |
| upper | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | converts all cased letters in the given string to uppercase |
Collection functions
| Function | Configuration type | Description |
|---|---|---|
| alltrue | .hcl | returns true if all elements in the given collection are true or "true", or if the collection is empty |
| anytrue | .hcl | returns true if any element in the given collection is true or "true", or the collection is empty |
| chunklist | .hcl | splits a single list into fixed-size chunks, returning a list of lists |
| coalesce | .hcl | takes any number of arguments and returns the first one that isn't null or an empty string |
| coalescelist | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes any number of list arguments and returns the first one that isn't empty |
| compact | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes a list of strings and returns a new list with any null or empty string elements removed |
| concat | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes two or more lists and combines them into a single list |
| contains | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | determines whether the list, tuple, or set given in its first argument contains at least one element that is equal to the value in the second argument |
| distinct | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes a list and returns a new list with any duplicate elements removed |
| element | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | retrieves a single element from a list |
| flatten | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes a list and replaces any elements that are lists with a flattened sequence of the list contents |
| index | .hcl | finds the first element for a given value in a list |
| keys | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes a map and returns a list containing the keys from that map |
| length | .hcl | returns the length of a given list, map, or string |
| length | .hcl | returns the length of a given list, map, or string |
| list | deprecated after Terraform 0.12. Use tolist instead | |
| lookup | .hcl | retrieves the value of a single element from a map, given its key |
| map | deprecated after Terraform 0.12. Use tomap instead | |
| matchkeys | .hcl | constructs a new list by taking a subset of elements from one list whose indexes match the corresponding indexes of values in another list |
| merge | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes an arbitrary number of maps or objects, and returns a single map or object that contains a merged set of elements from all arguments |
| one | .hcl | returns the only element in the given list, set, or tuple, null if the given argument is empty, or raises an error if it has more than one value |
| range | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | generates a list of numbers using a start value, a limit value, and a step value |
| reverse | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes a sequence and produces a new sequence of the same length with all of the same elements as the given sequence but in reverse order |
| setintersection | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes multiple sets and produces a single set containing only the elements that all of the given sets have in common |
| setproduct | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | finds all of the possible combinations of elements from all of the given sets by computing the Cartesian product |
| setsubtract | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | returns a new set containing the elements from the first set that are not present in the second set |
| setunion | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes multiple sets and produces a single set containing the elements from all of the given sets |
| slice | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | extracts some consecutive elements from within a list |
| sort | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes a list of strings and returns a new list with those strings sorted lexicographically |
| sum | .hcl | takes a list or set of numbers and returns the sum of those numbers |
| transpose | .hcl | takes a map of lists of strings and swaps the keys and values to produce a new map of lists of strings |
| values | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | takes a map and returns a list containing the values of the elements in that map |
| zipmap | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | constructs a map from a list of keys and a corresponding list of values |
Encoding functions
| Function | Configuration type | Description |
|---|---|---|
| base64decode | .hcl | takes a string containing a Base64 character sequence and returns the original string |
| base64encode | .hcl | applies Base64 encoding to a string and returns the encoded string |
| base64gzip | .hcl | compresses an HCL string using gzip and then encodes the string using Base64 encoding |
| csvdecode | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | decodes a string containing CSV-formatted data and produces a list of maps representing that data |
| jsondecode | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | interprets a given string as JSON, returning a representation of the result of decoding that string |
| jsonencode | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | encodes a given value to a string using JSON syntax |
| textdecodebase64 | .hcl | decodes a string that was previously Base64-encoded, and then interprets the result as characters in a specified character encoding |
| textencodebase64 | .hcl | encodes the unicode characters in a given string using a specified character encoding, returning the result base64 encoded |
| textencodebase64 | .hcl | encodes the unicode characters in a given string using a specified character encoding, returning the result base64 encoded |
| urlencode | .hcl | applies URL encoding to a given string |
| yamldecode | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | parses a string as a subset of YAML, and produces a representation of its value |
| yamlencode | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | encodes a given value to a string using YAML 1.2 block syntax |
Filesystem functions
| Function | Configuration type | Description |
|---|---|---|
| abspath | .hcl | takes a string containing a filesystem path and converts it to an absolute path |
| dirname | .hcl | takes a string containing a filesystem path and removes the last portion from it |
| pathexpand | .hcl | takes a filesystem path that might begin with a ~ segment, and if so it replaces that segment with the current user's home directory path |
| basename | .hcl | takes a string containing a filesystem path and removes all except the last portion from it |
| file | .hcl | reads the contents of a file at the given path and returns them as a string |
| fileexists | .hcl | determines whether a file exists at a given path |
| fileset | .hcl | enumerates a set of regular file names given a path and pattern |
| filebase64 | .hcl | reads the contents of a file at the given path and returns them as a base64-encoded string |
| templatefile | .hcl | reads the file at the given path and renders its content as a template using a supplied set of template variables |
Date and time functions
| Function | Configuration type | Description |
|---|---|---|
| formatdate | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | converts a timestamp into a different time format |
| plantimestamp | .hcl | returns a UTC timestamp string in RFC 3339 format at the time Terraform creates a plan |
| timeadd | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | adds a duration to a timestamp, returning a new timestamp |
| timecmp | .hcl | compares two timestamps and returns a number that represents the ordering of the instants those timestamps represent |
| timestamp | .hcl | returns a UTC timestamp string in RFC 3339 format at the current time |
Hash and crypto functions
| Function | Configuration type | Description |
|---|---|---|
| base64sha256 | .hcl | computes the SHA256 hash of a given string and encodes it with Base64 |
| base64sha512 | .hcl | computes the SHA512 hash of a given string and encodes it with Base64 |
| bcrypt | .hcl | computes a hash of the given string using the Blowfish cipher, returning a string in the Modular Crypt Format |
| filebase64sha256 | .hcl | is a variant of base64sha256 that hashes the contents of a given file rather than a literal string |
| filebase64sha512 | .hcl | is a variant of base64sha512 that hashes the contents of a given file rather than a literal string |
| filemd5 | .hcl | is a variant of md5 that hashes the contents of a given file rather than a literal string |
| filesha1 | .hcl | is a variant of sha1 that hashes the contents of a given file rather than a literal string |
| filesha256 | .hcl | calculates the SHA-256 hash of a file's contents |
| filesha512 | .hcl | calculates the SHA-512 hash of a file's contents |
| md5 | .hcl | computes the MD5 hash of a given string and encodes it with hexadecimal digits |
| rsadecrypt | .hcl | decrypts an RSA-encrypted ciphertext, returning the corresponding cleartext |
| sha1 | .hcl | computes the SHA1 hash of a given string and encodes it with hexadecimal digits |
| sha256 | .hcl | computes the SHA256 hash of a given string and encodes it with hexadecimal digits |
| sha512 | .hcl | computes the SHA512 hash of a given string and encodes it with hexadecimal digits |
| uuid | .hcl | generates UUID-format strings using random bytes |
| uuidv5 | .hcl | generates a name-based UUID, as described in RFC 4122 section 4.3 |
IP network functions
| Function | Configuration type | Description |
|---|---|---|
| cidrhost | .hcl | calculates a full host IP address for a given host number within a given IP network address prefix |
| cidrnetmask | .hcl | converts an IPv4 address prefix given in CIDR notation into a subnet mask address |
| cidrsubnet | .hcl | calculates a subnet address within given IP network address prefix |
| cidrsubnets | .hcl | calculates a sequence of consecutive IP address ranges within a particular CIDR prefix |
Type conversion functions
| Function | Configuration type | Description |
|---|---|---|
| can | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | evaluates the given expression and returns a boolean value indicating whether the expression produced a result without any errors |
| ephemeralasnull | .hcl | accepts an ephemeral value and returns null |
| issensitive | .hcl | takes any value and returns true if Terraform treats it as sensitive |
| nonsensitive | .hcl | takes a sensitive value and returns a copy of that value with the sensitive marking removed, thereby exposing the sensitive value |
| sensitive | .hcl | takes any value and returns a copy of it marked so that Terraform will treat it as sensitive |
| tobool | .hcl | converts its argument to a boolean value |
| tolist | .hcl | converts its argument to a list value |
| tomap | .hcl | converts its argument to a map value |
| tonumber | .hcl | converts its argument to a number value |
| toset | .hcl | converts its argument to a set value |
| tostring | .hcl | converts its argument to a string value |
| try | .hcl, .tfcomponent.hcl, .tfdeploy.hcl | evaluates all of its argument expressions in turn and returns the result of the first one that does not produce any errors |
| type | .hcl | returns the type of a given value |
Terraform-specific functions
| Function | Configuration type | Description |
|---|---|---|
| provider::terraform::encode_tfvars | .hcl | takes an object value and produces a string containing a description of that object |
| provider::terraform::decode_tfvars | .hcl | takes a string containing the content of a .tfvars file and returns an object describing the raw variable values it defines |
| provider::terraform::encode_expr | .hcl | takes any value and produces a string containing Terraform language expression syntax approximating that value |
| type | .hcl | returns the type of a given value |