Connect to Terraform Cloud

This page explains how to connect Terraform Cloud 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

After you sign up for a Terraform Cloud Account, you must connect your CDKTF project to one or more Terraform Cloud 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 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.

Connect New CDKTF Projects

For new projects, do the following:

1. Run cdktf init without passing the --local flag. This creates a new template CDKTF project for your chosen programming language. Templates generate a new application with the necessary file structure for you to start defining infrastructure.
2. Choose a project language and provide a project name and description.
3. Log in to Terraform Cloud. CDKTF uses saved credentials or asks you to log in.
4. Select a Terraform Cloud organization and a name for your workspace.
5. Choose whether to send crash reports to the CDKTF team.

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

Connect Existing CDKTF Projects

For existing projects, do the following:

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

2. Add the RemoteBackend to your CDKTF application. The following example connects the application to a Terraform Cloud 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();
   

3. Run cdktf login and log in to Terraform Cloud.

Your CDKTF application is connected to the Terraform Cloud 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 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 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.

1. 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
     }
   }
   

2. Add variables that you declared in your CDKTF application to your Terraform Cloud 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 in a CI workflow, you can either use Terraform Cloud's VCS-driven workflow or use a general-purpose CI to trigger the run in Terraform Cloud.

Policy Enforcement

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.