Build AWS Infrastructure with CDK for Terraform

The Cloud Development Kit for Terraform (CDKTF) allows you to define your infrastructure in a familiar programming language such as TypeScript, Python, Go, C#, or Java. CDKTF generates Terraform configuration in JSON, then automatically applies that configuration via Terraform to provision your infrastructure.

In this tutorial, you will provision an EC2 instance on AWS using your preferred programming language.

If you do not have CDKTF installed on your system, follow the steps in the install CDKTF tutorial to install it before you continue with this tutorial.

»Prerequisites

To follow this tutorial, you need the following installed locally:

Terraform v1.0+
A Terraform Cloud account, with CLI authentication configured
CDK for Terraform v0.8+
an AWS account
AWS Credentials configured for use with Terraform

Terraform and CDKTF will use credentials set in your environment or through other means as described in the Terraform documentation.

You will also need to install a recent version of the programming language you will use for this tutorial. We have verified this tutorial works with the following language versions.

Typescript v4.4 and Node.js v16.13

»Initialize a new CDK for Terraform application

Start by creating a directory named learn-cdktf for your project.

$ mkdir learn-cdktf

$ mkdir learn-cdktf

Then navigate into it.

$ cd learn-cdktf

$ cd learn-cdktf

Inside the directory, run cdktf init, specifying the template for your preferred language.

Tip: If you would prefer to keep your state locally, use the --local flag with cdktf init.

$ cdktf init --template="typescript"
? Project Name learn-cdktf
? Project Description A simple getting started project for cdktf.

Detected Terraform Cloud token.

We will now set up Terraform Cloud for your project.

? Terraform Cloud Organization Name <YOUR_ORG>

We are going to create a new Terraform Cloud Workspace for your project.

? Terraform Cloud Workspace Name learn-cdktf

Setting up remote state backend and workspace in Terraform Cloud.

Generating Terraform Cloud configuration for '<YOUR_ORG>' organization and 'learn-cdktf' workspace.....

## ...

========================================================================================================

  Your cdktf typescript project is ready!

## ...

 Use Prebuilt Providers:

  You can find all prebuilt providers on npm: https://www.npmjs.com/search?q=keywords:cdktf
  You can install these providers through npm:

  npm install @cdktf/provider-aws
  npm install @cdktf/provider-google
  npm install @cdktf/provider-azurerm
  npm install @cdktf/provider-docker
  npm install @cdktf/provider-github
  npm install @cdktf/provider-null

  You can also build any module or provider locally. Learn more https://cdk.tf/modules-and-providers

========================================================================================================

$ cdktf init --template="typescript"
? Project Name learn-cdktf
? Project Description A simple getting started project for cdktf.

Detected Terraform Cloud token.

We will now set up Terraform Cloud for your project.

? Terraform Cloud Organization Name <YOUR_ORG>

We are going to create a new Terraform Cloud Workspace for your project.

? Terraform Cloud Workspace Name learn-cdktf

Setting up remote state backend and workspace in Terraform Cloud.

Generating Terraform Cloud configuration for '<YOUR_ORG>' organization and 'learn-cdktf' workspace.....

## ...

========================================================================================================

  Your cdktf typescript project is ready!

## ...

 Use Prebuilt Providers:

  You can find all prebuilt providers on npm: https://www.npmjs.com/search?q=keywords:cdktf
  You can install these providers through npm:

  npm install @cdktf/provider-aws
  npm install @cdktf/provider-google
  npm install @cdktf/provider-azurerm
  npm install @cdktf/provider-docker
  npm install @cdktf/provider-github
  npm install @cdktf/provider-null

  You can also build any module or provider locally. Learn more https://cdk.tf/modules-and-providers

========================================================================================================

This will initialize a brand new CDK for Terraform project using an interactive command. Accept the defaults for "Project Name" and "Project Description". Select your Terraform Cloud Organization, and choose the name learn-cdktf for the Terraform Cloud Workspace.

»Install AWS provider

CDKTF provides packages with prebuilt classes for several common Terraform providers that you can use in your TypeScript projects. For other Terraform providers and modules, you can add them to cdktf.json and use cdktf get to generate the appropriate TypeScript classes.

Install the AWS provider with npm.

$ npm install @cdktf/provider-aws
+ @cdktf/provider-aws@4.0.11
added 1 package from 1 contributor and audited 395 packages in 6.266s

30 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

$ npm install @cdktf/provider-aws
+ @cdktf/provider-aws@4.0.11
added 1 package from 1 contributor and audited 395 packages in 6.266s

30 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

»Define your CDK for Terraform Application

Open the main.ts file to view your application code. The template creates a scaffold with no functionality.

Replace the contents of main.ts with the following code for a new TypeScript application, which uses the CDK to provision an AWS EC2 instance in us-west-1, and stores its state in Terraform Cloud.

import { Construct } from "constructs";
import { App, TerraformStack, TerraformOutput, RemoteBackend } from "cdktf";
import { AwsProvider, ec2 } from "@cdktf/provider-aws";

class MyStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new AwsProvider(this, "AWS", {
      region: "us-west-1",
    });

    const instance = new ec2.Instance(this, "compute", {
      ami: "ami-01456a894f71116f2",
      instanceType: "t2.micro",
    });

    new TerraformOutput(this, "public_ip", {
      value: instance.publicIp,
    });
  }
}

const app = new App();
const stack = new MyStack(app, "aws_instance");

new RemoteBackend(stack, {
  hostname: "app.terraform.io",
  organization: "<YOUR_ORG>",
  workspaces: {
    name: "learn-cdktf",
  },
});

app.synth();

main.ts

import { Construct } from "constructs";
import { App, TerraformStack, TerraformOutput, RemoteBackend } from "cdktf";
import { AwsProvider, ec2 } from "@cdktf/provider-aws";

class MyStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new AwsProvider(this, "AWS", {
      region: "us-west-1",
    });

    const instance = new ec2.Instance(this, "compute", {
      ami: "ami-01456a894f71116f2",
      instanceType: "t2.micro",
    });

    new TerraformOutput(this, "public_ip", {
      value: instance.publicIp,
    });
  }
}

const app = new App();
const stack = new MyStack(app, "aws_instance");

new RemoteBackend(stack, {
  hostname: "app.terraform.io",
  organization: "<YOUR_ORG>",
  workspaces: {
    name: "learn-cdktf",
  },
});

app.synth();

Replace <YOUR_ORG> with the Terraform Cloud organization name you chose when you ran terraform init earier.

Tip: If you would prefer to store your project's state locally, remove or comment out new RemoteBackend(stack, { [...] }); and remove RemoteBackend from the import { [...] } from "cdktf"; line near the top of the file.

»Examine the code

Most of the code is similar to concepts found in a traditional Terraform configuration written in HCL, but there are a few notable differences. Review the code for the programming language you have selected.

You must explicitly import any classes your TypeScript code uses. For example, you will use TerraformOutput to create a Terraform output value for your EC2 instance's public IP address.

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

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

The code imports the AwsProvider and ec2 classes from the provider you installed earlier with npm install.

import { AwsProvider, ec2 } from "@cdktf/provider-aws";

import { AwsProvider, ec2 } from "@cdktf/provider-aws";

The example code defines a new stack, which contains the code to define your provider and all of your resources.

class MyStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

class MyStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

The code configures the AWS provider to use the us-west-1 region.

    new AwsProvider(this, "AWS", {
      region: "us-west-1",
    });

    new AwsProvider(this, "AWS", {
      region: "us-west-1",
    });

The example code configures the AwsProvider by passing in an object with keys and values that map to Terraform arguments as listed in the AWS provider documentation.

The code defines a compute instance with the ec2.Instance class.

    const instance = new ec2.Instance(this, "compute", {
      ami: "ami-01456a894f71116f2",
      instanceType: "t2.micro",
    });

    const instance = new ec2.Instance(this, "compute", {
      ami: "ami-01456a894f71116f2",
      instanceType: "t2.micro",
    });

The code also configures the instance with an object, using camel case for properties that correspond to the AWS provider documentation.

The code stores the instance as a variable so that the TerraformOutput below can reference the instance's publicIp attribute.

    new TerraformOutput(this, "public_ip", {
      value: instance.publicIp,
    });

    new TerraformOutput(this, "public_ip", {
      value: instance.publicIp,
    });

When you write CDKTF code with an IDE, use it view the properties and functions of the classes, variables, and packages in your code. This example uses the publicIp attribute from the instance variable.

Finally, the example code creates your application using the stack you have defined, configures a remote backend to store your project's state in Terraform Cloud, and runs app.synth() to generate Terraform configuration.

const app = new App();
new MyStack(app, "aws_instance");

new RemoteBackend(stack, {
  hostname: "app.terraform.io",
  organization: "<YOUR_ORG>",
  workspaces: {
    name: "learn-cdktf"
  }
});

app.synth();

const app = new App();
new MyStack(app, "aws_instance");

new RemoteBackend(stack, {
  hostname: "app.terraform.io",
  organization: "<YOUR_ORG>",
  workspaces: {
    name: "learn-cdktf"
  }
});

app.synth();

»Provision infrastructure

Now that you have initialized the project with the AWS provider and written code to provision an instance, it's time to deploy it by running cdktf deploy. When CDKTF asks you to confirm the deploy, respond with a yes.

$ cdktf deploy
Deploying Stack: aws_instance
Resources
 ✔ AWS_INSTANCE         compute             aws_instance.compute

Summary: 1 created, 0 updated, 0 destroyed.

Output: public_ip = 50.18.17.102

$ cdktf deploy
Deploying Stack: aws_instance
Resources
 ✔ AWS_INSTANCE         compute             aws_instance.compute

Summary: 1 created, 0 updated, 0 destroyed.

Output: public_ip = 50.18.17.102

The cdktf deploy command runs terraform apply in the background.

After the instance is created, visit the AWS EC2 Dashboard.

Notice that the CDK deploy command printed out the public_ip output value, which matches the instance's public IPv4 address.

»Change infrastructure by adding the Name tag

Add a tag to the EC2 instance.

Update the ec2.Instance in main.ts to add a Name tag.

     const instance = new ec2.Instance(this, "compute", {
       ami: "ami-01456a894f71116f2",
       instanceType: "t2.micro",
+      tags: {
+        Name: "CDKTF-Demo",
+      },
     });

main.ts

     const instance = new ec2.Instance(this, "compute", {
       ami: "ami-01456a894f71116f2",
       instanceType: "t2.micro",
+      tags: {
+        Name: "CDKTF-Demo",
+      },
     });

Deploy your updated application. Confirm your deploy with a yes.

$ cdktf deploy
Deploying Stack: aws_instance
Resources
 ✔ AWS_INSTANCE         compute             aws_instance.compute

Summary: 0 created, 1 updated, 0 destroyed.

Output: public_ip = 50.18.17.102

$ cdktf deploy
Deploying Stack: aws_instance
Resources
 ✔ AWS_INSTANCE         compute             aws_instance.compute

Summary: 0 created, 1 updated, 0 destroyed.

Output: public_ip = 50.18.17.102

»Clean up your infrastructure

Destroy the application by running cdktf destroy. Confirm your run with a yes.

$ cdktf destroy
Destroying Stack: aws_instance
Resources
 ✔ AWS_INSTANCE         compute             aws_instance.compute

Summary: 1 destroyed.

$ cdktf destroy
Destroying Stack: aws_instance
Resources
 ✔ AWS_INSTANCE         compute             aws_instance.compute

Summary: 1 destroyed.

Destroying your CDKTF application will not remove the Terraform Cloud workspace that stores your project's state. If you don't want to run this example again, log into the Terraform Cloud application and delete the workspace.

»Next steps

Now you have deployed, modified, and deleted an AWS EC2 instance using CDKTF!

CDKTF is capable of much more. For example, you can:

Use the cdktf synth command to generate JSON which can be used by the Terraform executable to provision infrastructure using terraform apply and other Terraform commands.
Use Terraform providers and modules.
Use programming language features (like class inheritance) or data from other sources to augment your Terraform configuration.
Use CDKTF with Terraform Cloud for persistent storage of your state file and for team collaboration.

For other examples, refer to the CDKTF documentation repository. In particular, check out the:

CDKTF Architecture documentation for an overview of CDKTF's architecture.
Community documentation to learn how to engage with the CDKTF developer community.
Review Example code in several programming languages.

Infrastructure

Security

Applications

Networking

cloud