Connect to Terraform Cloud / Enterprise

This page explains how to connect Terraform Cloud / Enterprise to your CDK for Terraform (CDKTF) application and the benefits of using these products together.

Hands On: Try our Get Started - Terraform Cloud tutorials.

What are Terraform Cloud and Terraform Enterprise?

CDKTF supports Terraform Cloud and Terraform Enterprise.

Terraform Cloud is a SaaS application that runs Terraform in a stable, remote environment and securely stores state and secrets. It includes a user interface that helps you better understand your Terraform operations and resources, allows you to define role-based access controls, and offers a private registry for sharing modules and providers. Terraform Cloud also integrates with the Terraform CLI and connects to common version control systems (VCS) like GitHub, GitLab, and Bitbucket. When you connect a Terraform Cloud workspace to a VCS repository, new commits and changes can automatically trigger Terraform plans. Terraform Cloud also offers an API, allowing you to integrate it into existing workflows.

Terraform Enterprise lets you set up a self-hosted distribution of Terraform Cloud and is ideal for organizations with strict security and compliance requirements.

When to use Terraform Cloud or Terraform Enterprise?

Terraform uses persisted state data to keep track of the real-world resources it manages. By default, Terraform writes state to a local file. We recommend integrating with Terraform Cloud to store state remotely. This prevents accidental loss of locally stored state and lets multiple people access the state data so they can work together on that collection of infrastructure resources.

Other benefits of Terraform Cloud and Terraform Enterprise include the ability to run Terraform remotely, manage variables and secrets, and enforce policies for sets of infrastructure.

Set up CDKTF with Terraform Cloud / Enterprise

After you sign up for a Terraform Cloud Account / create an account in your Terraform Enterprise instance, you must connect your CDKTF project to one or more workspaces.

Workspaces function like working directories for distinct Terraform configurations and are associated with a Terraform configuration and its state file. They can also contain variables that you can use to manage credentials.

Workspaces can have one of three workflows that determine how Terraform Cloud / Enterprise interacts with your CDKTF application: CLI-driven, Version control, or API-driven (a more advanced option).

CLI-driven Workflow

You can configure the Terraform Cloud CLI-driven workflow for both new and existing CDKTF projects. This workflow lets you run CDKTF CLI commands to deploy your application and run Terraform operations remotely on Terraform Cloud / Enterprise.

Connect New CDKTF Projects

First use cdktf login to log into Terraform Cloud or your Terraform Enterprise instance:

This command will take you through an interactive session to log in.

```shell-session
$ cdktf login
```

If you already have a Terraform Cloud API token, you can pass it into stdin:

```shell-session
cat my-token.txt | cdktf login
```

This command will take you through an interactive session to log in.

```shell-session
$ cdktf login --tfe-hostname tfe.my-company.com
```

If you already have a Terraform Enterprise API token, you can pass it into stdin:

```shell-session
cat my-token.txt | cdktf login --tfe-hostname tfe.my-company.com
```

Run cdktf init without passing the --local flag. This creates a new template CDKTF project for your chosen programming language. It will be the basis for a new application with the necessary file structure for you to start defining infrastructure. If you're using Terraform Enterprise, you must also pass the --tfe-hostname flag with the hostname of your enterprise instance.
Choose a project language and provide a project name and description.
Select a Terraform Cloud organization and a name for your workspace. CDKTF will create a CloudBackend in your project.
You can choose whether to send crash reports to the CDKTF team and select the providers you want to use.

CDKTF creates both a scaffolded project in your chosen language and a new Terraform Cloud workspace on first apply. Your project is connected to the workspace and you can begin using CDKTF and Terraform Cloud together. By default, the workspace is set to Remote execution mode, which means Terraform runs remotely on Terraform Cloud / Enterprise. If you want Terraform to run locally, you need to set the workspace to Local Execution mode.

Connect Existing CDKTF Projects

For existing projects, do the following:

Create a Terraform Cloud workspace with the CLI-driven workflow.

Add the RemoteBackend to your CDKTF application. The following example connects the application to a Terraform Cloud / Enterprise workspace called my-app-prod.

import { Construct } from "constructs";
import { App, TerraformStack, RemoteBackend } from "cdktf";

class MyStack extends TerraformStack {
  constructor(scope: Construct, name: string) {
    super(scope, name);
    // Remote Backend - /docs/backends/types/remote.html
    new RemoteBackend(this, {
      // Only required for self-hosted Terraform Enterprise instances.
      // Defaults to "app.terraform.io".
      hostname: "app.terraform.io",
      organization: "company",

      workspaces: {
        name: "my-app-prod",
      },
    });

    // define resources here
  }
}

const app = new App();
const myStack = new MyStack(app, "my-stack");
// You can also define the backend outside of the stack.
// new RemoteBackend(myStack, {
//     hostname: "app.terraform.io",
//     organization: "company",

//     workspaces: {
//     name: "my-app-prod",
//     },
// });
// You must configure the RemoteBackend before the app.synth() call
app.synth();

Run cdktf login / cdktf login --tfe-hostname=tfe.my-company.com and log in to Terraform Cloud / Enterprise.

Your CDKTF application is connected to the Terraform Cloud / Enterprise workspace you specified in the RemoteBackend. You must set the workspace to Remote Execution mode if you want to store state and run Terraform operations remotely.

VCS-driven Workflow

Check your synthesized code into version control and connect your Terraform Cloud / Enterprise workspace to that repository with the VCS-driven workflow. You can configure the workspace to trigger Terraform runs based on merges and commits to the repository. Refer to Deployment Patterns for more details about how to use CDKTF with the VCS-driven workflow.

Managing Variables and Secrets

Terraform Cloud / Enterprise variables let you define the variables and secrets that Terraform uses during remote operations. You can set variables specifically for each workspace or you can create variable sets to reuse the same variables across multiple workspaces. For example, you could define a variable set of provider credentials and automatically apply it to all of the workspaces using that provider.

To use variables, set your workspace to Remote Execution Mode. Terraform can only access workspace variables when executing remotely on Terraform Cloud / Enterprise.

Use the TerraformVariable construct to declare variables in your CDKTF application. This creates an undefined Terraform input variable. The following example demonstrates how to create a TerraformVariable called my-var.

import { Construct } from "constructs";
import { App, TerraformStack, TerraformVariable } from "cdktf";

class MyStack extends TerraformStack {
  constructor(scope: Construct, name: string) {
    super(scope, name);
    // You can define 'my-var' in Terraform Cloud and use the value in your application.
    const value = new TerraformVariable(this, "my-var", {
      default: "The default value to use",
      description: "",
      nullable: false, // if passing no
      sensitive: true,
      type: "string",
    });

    // define resources here
  }
}

Add variables that you declared in your CDKTF application to your Terraform Cloud / Enterprise workspace. Refer to Add a Variable for details. This lets Terraform access the value during operations.

Variable Return Values

The return value for TerraformVariable is an object with various representations of the value as attributes. You can pass this object as a string with value.stringValue, as a number with value.numberValue, or as a list with value.listValue.

This means that there is no actual value in the variable field when CDKTF synthesizes your application. Instead, CDKTF uses a Token, which represents a value that is unknown until Terraform applies your configuration. You cannot use tokens in dynamic checks during runtime. For example, if (value.listValue.length > 42) { always returns false because tokenized lists have a static length of one item.

Continuous Integration

To run Terraform Cloud / Enterprise in a CI workflow, you can either use Terraform Cloud / Enterprise's VCS-driven workflow or use a general-purpose CI to trigger the run in Terraform Cloud / Enterprise.

Policy Enforcement

+-> Note: Refer to Terraform Cloud pricing for more information about Sentinel policies and run tasks.

You can define Sentinel policies for one or multiple Terraform Cloud workspaces to ensure that your infrastructure follows company-wide security standards and best practices. You can use Sentinel policies with CDKTF if Terraform Cloud is configured as a Remote Backend.

You can also use Run Tasks to directly integrate third-party tools and services at certain stages in the Terraform Cloud run lifecycle. Terraform Cloud uses the status response from the third-party tool to determine if a run should proceed.