Functions

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 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 CDKTF 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 } from "cdktf";
import { Construct } from "constructs";
import { AwsProvider } from "@cdktf/provider-aws/lib/aws-provider";
import { Fn, TerraformOutput } from "cdktf";
import { DataAwsAvailabilityZones } from "@cdktf/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),
    });
  }
}

Operators

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

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

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

// ...

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

Using Terraform built-in functions directly within strings

It is also possible to use all built-in Terraform functions without using CDKTF'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: CDKTF 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 "cdktf";
import { Op } from "cdktf";
import { DataAwsAvailabilityZones } from "@cdktf/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}`,
});