Terraform provides a set of built-in functions that transform and combine values within Terraform configurations. The Terraform function documentation contains a complete list. You can also use your editor autocompletion on the Fn object to find available options. Functions can handle normal and token values and will return either tokenized values or IResolvable values.

When to Use Terraform Functions

Use Terraform functions when you need to calculate new values based on runtime values that are unknown before Terraform (or OpenTofu) applies a configuration. For example, instance IDs that cloud providers assign on creation. When inputs are available before synthesizing your code (e.g. local files), we recommend transforming the values with your preferred programming language.

Usage Example

The following example uses a Data Source from the AWS Provider to fetch the Availability Zones of the given region. As this data is unknown until Terraform applies the configuration, this CDKTN application uses both Terraform Outputs and the Terraform element function. The element function gets the first element from the list of Availability Zone names.

import { TerraformStack, TerraformVariable } from "cdktn";
import { Construct } from "constructs";
import { AwsProvider } from "@cdktn/provider-aws/lib/aws-provider";
import { Fn, TerraformOutput } from "cdktn";
import { DataAwsAvailabilityZones } from "@cdktn/provider-aws/lib/data-aws-availability-zones";
export class FunctionsStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new AwsProvider(this, "aws", {
      region: "us-west-2",
    });

    const zones = new DataAwsAvailabilityZones(this, "zones", {
      state: "available",
    });
    new TerraformOutput(this, "first-zone", {
      value: Fn.element(zones.names, 0),
    });
  }
}

import io.cdktn.cdktn.Fn;
import io.cdktn.cdktn.TerraformVariable;
import io.cdktn.cdktn.TerraformVariableConfig;
import io.cdktn.cdktn.TerraformOutput;
import io.cdktn.cdktn.TerraformOutputConfig;
import imports.aws.data_aws_availability_zones.DataAwsAvailabilityZones;
import imports.aws.data_aws_availability_zones.DataAwsAvailabilityZonesConfig;

        DataAwsAvailabilityZones zones = new DataAwsAvailabilityZones(this, "zones",
                DataAwsAvailabilityZonesConfig.builder()
                        .state("available")
                        .build());

        new TerraformOutput(this, "first-zone", TerraformOutputConfig.builder()
                .value(Fn.element(zones.getNames(), 0))
                .build());

from cdktn import Fn, TerraformOutput
from imports.aws.provider import AwsProvider
from imports.aws.data_aws_availability_zones import DataAwsAvailabilityZones

        zones = DataAwsAvailabilityZones(self, 'zones',
                    state="available",
                )

        TerraformOutput(self, 'first-zone',
            value=Fn.element(zones.names, 0)
        )

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using Io.Cdktn;
using aws.Provider;
using aws.DataAwsAvailabilityZones;

namespace Examples
{
    class FunctionStack : TerraformStack
    {
        public FunctionStack(Construct scope, string name) : base(scope, name)
        {

            new AwsProvider(this, "aws", new AwsProviderConfig
            {
                Region = "eu-central-1"
            });

            DataAwsAvailabilityZones zones = new DataAwsAvailabilityZones(this, "zones", new DataAwsAvailabilityZonesConfig
            {
                State = "available"
            });

            new TerraformOutput(this, "first-zone", new TerraformOutputConfig
            {
                Value = Fn.Element(zones.Names, 0)
            });
        }
    }
}

import (
	"github.com/aws/constructs-go/constructs/v10"
	"github.com/aws/jsii-runtime-go"
	"github.com/open-constructs/cdk-terrain-go/cdktn"
	"github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/dataawsavailabilityzones"
	aws "github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/provider"
)

func NewFunctionsStack(scope constructs.Construct, name string) cdktn.TerraformStack {
	stack := cdktn.NewTerraformStack(scope, &name)

	aws.NewAwsProvider(stack, jsii.String("aws"), &aws.AwsProviderConfig{
		Region: jsii.String("use-west-2"),
	})

	zones := dataawsavailabilityzones.NewDataAwsAvailabilityZones(stack, jsii.String("zones"), &dataawsavailabilityzones.DataAwsAvailabilityZonesConfig{
		State: jsii.String("available"),
	})

	cdktn.NewTerraformOutput(stack, jsii.String("first-zone"), &cdktn.TerraformOutputConfig{
		Value: cdktn.Fn_Element(cdktn.Token_AsAny(zones.Names()), jsii.Number(0)),
	})

	return stack
}

Special functions

Property Access Helpers

To access nested properties from untyped objects or other datasources that return a dynamic datatype, use the Terraform function lookup or, for nested access, the function “Fn.lookupNested()” which is a function offered by CDKTN that allows to avoid nesting Fn.lookup calls.

const v = new TerraformVariable(this, "complex_object", {
  type: "object({users: list(object({name: string}))})",
});
new TerraformOutput(this, "users", { value: Fn.lookup(v.value, "users") });
new TerraformOutput(this, "first_user_name", {
  value: Fn.lookupNested(v.value, ["users", 0, "name"]),
});

v = TerraformVariable(self, "complex-object",
    type = 'object({users: list(object({name: string}))})',
)
TerraformOutput(self, 'users',
    value=Fn.lookup(v.string_value, "users")
)
TerraformOutput(self, 'first_user_name',
    value=Fn.lookup_nested(v.string_value, ["users", 0, "name"])
)

TerraformVariable v = new TerraformVariable(this, "complex_object", TerraformVariableConfig.builder()
        .type("object({users: list(object({name: string}))})")
        .build());
new TerraformOutput(this, "users", TerraformOutputConfig.builder()
        .value(Fn.lookup(v.getValue(), "users"))
        .build());
new TerraformOutput(this, "first-user-name", TerraformOutputConfig.builder()
        .value(Fn.lookupNested(v.getValue(), Arrays.asList("users", "0", "name")))
        .build());

TerraformVariable v = new TerraformVariable(this, "complex_object", new TerraformVariableConfig
{
    Type = "object({users: list(object({name: string}))})",
});
new TerraformOutput(this, "users", new TerraformOutputConfig
{
    Value = Fn.Lookup(v.Value, "users")
});
new TerraformOutput(this, "first-user-name", new TerraformOutputConfig
{
    Value = Fn.LookupNested(v.Value, new[] { "users", "0", "name" })
});

v := cdktn.NewTerraformVariable(stack, jsii.String("complex-object"), &cdktn.TerraformVariableConfig{
	Type: jsii.String("object({users: list(object({name: string}))})"),
})
cdktn.NewTerraformOutput(stack, jsii.String("users"), &cdktn.TerraformOutputConfig{
	Value: cdktn.Fn_Lookup(v.Value(), jsii.String("users"), nil),
})
cdktn.NewTerraformOutput(stack, jsii.String("first-user-name"), &cdktn.TerraformOutputConfig{
	Value: cdktn.Fn_LookupNested(v.Value(), &[]interface{}{"users", 0, "name"}),
})

Raw string helper

Another helper function offered by CDKTN is Fn.rawString which can be used to escape raw strings that contain characters that CDKTN or Terraform would try to interpret otherwise.

new TerraformOutput(this, "quotes", {
  value: Fn.rawString(`"b"`),
});
new TerraformOutput(this, "template", {
  value: Fn.rawString("${TEMPLATE}"),
});

TerraformOutput(self, 'quotes',
    value=Fn.raw_string('"b"')
)
TerraformOutput(self, 'template',
    value=Fn.raw_string('${TEMPLATE}')
)

new TerraformOutput(this, "quotes", TerraformOutputConfig.builder()
        .value(Fn.rawString("\"b\""))
        .build());
new TerraformOutput(this, "template", TerraformOutputConfig.builder()
        .value(Fn.rawString("${TEMPLATE}"))
        .build());

new TerraformOutput(this, "quotes", new TerraformOutputConfig
{
    Value = Fn.RawString("\"b\"")
});
new TerraformOutput(this, "template", new TerraformOutputConfig
{
    Value = Fn.RawString("${TEMPLATE}")
});

cdktn.NewTerraformOutput(stack, jsii.String("quotes"), &cdktn.TerraformOutputConfig{
	Value: cdktn.Fn_RawString(jsii.String("\"b\"")),
})
cdktn.NewTerraformOutput(stack, jsii.String("template"), &cdktn.TerraformOutputConfig{
	Value: cdktn.Fn_RawString(jsii.String("${TEMPLATE}")),
})

Operators

Use the Op object to include operators like !, +, and -.

import { Fn, TerraformOutput } from "cdktn";
import { Op } from "cdktn";

const zones = new DataAwsAvailabilityZones(this, "zones", {
  state: "available",
});

// ...

new TerraformOutput(this, "half-of-the-zone", {
  value: Op.div(Fn.lengthOf(zones.names), 2),
});

            DataAwsAvailabilityZones zones = new DataAwsAvailabilityZones(this, "zones", new DataAwsAvailabilityZonesConfig {
                State = "available"
            });

            new TerraformOutput(this, "half-of-the-zone", new TerraformOutputConfig {
                Value = Op.Div(Fn.LengthOf(Token.AsList(zones.Names)), 2)
            });

import (
	"fmt"

	"github.com/aws/constructs-go/constructs/v10"
	"github.com/aws/jsii-runtime-go"
	"github.com/open-constructs/cdk-terrain-go/cdktn"
	"github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/dataawsavailabilityzones"
	aws "github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/provider"
)

	zones := dataawsavailabilityzones.NewDataAwsAvailabilityZones(stack, jsii.String("zones"),
		&dataawsavailabilityzones.DataAwsAvailabilityZonesConfig{
			State: jsii.String("available"),
		},
	)

	cdktn.NewTerraformOutput(stack, jsii.String("half-of-the-zone"), &cdktn.TerraformOutputConfig{
		Value: cdktn.Op_Div(
			cdktn.Fn_LengthOf(cdktn.Token_AsAny(zones.Names())),
			jsii.Number(2),
		),
	})

Using Terraform built-in functions directly within strings

It is also possible to use all built-in Terraform functions without using CDKTN’s Fn.* functions described above. To write Terraform built-in functions the same as you would in HCL, simply wrap the desired string within the HCL ${ and } syntax. Note: CDKTN doesn’t do any further processing within the escaped syntax (${ and }), and thus is unable to handle nested escape syntaxes yet.

import { Fn, TerraformOutput } from "cdktn";
import { Op } from "cdktn";
import { DataAwsAvailabilityZones } from "@cdktn/provider-aws/lib/data-aws-availability-zones";

const zones = new DataAwsAvailabilityZones(this, "zones", {
  state: "available",
});

// ...

new TerraformOutput(this, "half-of-the-zone-raw", {
  value: `\${length(${zones.fqn}.names) / 2}`,
});

            DataAwsAvailabilityZones zones = new DataAwsAvailabilityZones(this, "zones", new DataAwsAvailabilityZonesConfig
            {
                State = "available"
            });

            new TerraformOutput(this, "half-of-the-zone", new TerraformOutputConfig
            {
                Value = $"${{length({zones.Fqn}.names) / 2}}"
            });

import (
	"fmt"

	"github.com/aws/constructs-go/constructs/v10"
	"github.com/aws/jsii-runtime-go"
	"github.com/open-constructs/cdk-terrain-go/cdktn"
	"github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/dataawsavailabilityzones"
	aws "github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/provider"
)

	zones := dataawsavailabilityzones.NewDataAwsAvailabilityZones(stack, jsii.String("zones"),
		&dataawsavailabilityzones.DataAwsAvailabilityZonesConfig{
			State: jsii.String("available"),
		},
	)

	cdktn.NewTerraformOutput(stack, jsii.String("half-of-the-zone-raw"), &cdktn.TerraformOutputConfig{
		Value: jsii.String(
			fmt.Sprintf("${length(%s.names) / 2}",
				*cdktn.Token_AsString(zones.Names(), &cdktn.EncodingOptions{}),
			),
		),
	})

Function Availability Across Terraform and OpenTofu

CDK Terrain works with both Terraform and OpenTofu, but the two products do not support the exact same set of built-in functions. The Fn class covers the union of both: most functions are available everywhere, while a few exist in only one product or were introduced in a later release. The bindings are generated from the function metadata of every stable Terraform release since 1.5.7 and every stable OpenTofu release since 1.6.0. Functions that are not universally available are listed below.

Function	Terraform	OpenTofu
`issensitive`	>= 1.8.0	>= 1.7.0
`templatestring`	>= 1.9.0	>= 1.7.0
`ephemeralasnull`	>= 1.10.0	>= 1.11.0
`convert`	>= 1.15.0	—
`base64gunzip`	—	>= 1.7.0
`cidrcontains`	—	>= 1.7.0
`urldecode`	—	>= 1.7.0

All other functions exposed on Fn are available in every supported release of both products.

Validating Function Usage at Synth Time

With the validateFunctionVersions feature flag enabled, CDK Terrain checks every function you use through Fn against the project’s declared targetVersions — the Terraform/OpenTofu version ranges your project intends to support. Projects created with cdktn init have the flag enabled by default; existing projects can opt in via cdktf.json:

{
  "targetVersions": {
    "terraform": ">=1.5.7",
    "opentofu": ">=1.6.0"
  },
  "context": {
    "validateFunctionVersions": "true"
  }
}

A function must be available across the entire declared range of every targeted product. If it is not, synthesis fails with an actionable error instead of letting terraform plan fail later:

Validation failed with the following errors:
  [MyStack/resource] Terraform function "templatestring" requires terraform >=1.9.0, but the project targets terraform >=1.5.7. It is available in terraform >=1.9.0 and opentofu >=1.7.0.

Raise the declared floor (e.g. "terraform": ">=1.9.0") — or drop the product you don’t support — to use the function.

The validation is purely declarative: it never executes a Terraform or OpenTofu binary, so synth behaves identically in CI, package builds, and environments without either installed. To explicitly verify the binary installed on a machine against the declared targets, opt in with "validateInstalledBinary": true, which applies to commands that execute the CLI (diff, deploy, destroy).

To disable all synth-time validations, pass skipValidation: true to your App configuration.

Limitations

Functions written inside raw expression strings (escape hatches such as overrides or hand-built ${...} interpolations) are not tracked and therefore not validated.
Provider-defined functions (provider::<name>::<function>) are out of scope; availability depends on the provider, not the CLI version.

Getting Started

Overview

Functions - CDK Terrain

When to Use Terraform Functions

Usage Example

Special functions

Property Access Helpers

Raw string helper

Operators

Using Terraform built-in functions directly within strings

Function Availability Across Terraform and OpenTofu

Validating Function Usage at Synth Time

Limitations

​When to Use Terraform Functions

​Usage Example

​Special functions

​Property Access Helpers

​Raw string helper

​Operators

​Using Terraform built-in functions directly within strings

​Function Availability Across Terraform and OpenTofu

​Validating Function Usage at Synth Time

​Limitations

When to Use Terraform Functions

Usage Example

Special functions

Property Access Helpers

Raw string helper

Operators

Using Terraform built-in functions directly within strings

Function Availability Across Terraform and OpenTofu

Validating Function Usage at Synth Time

Limitations