Build AWS Infrastructure with TypeScript

CDK for Terraform (CDKTF) allows you to define your infrastructure in a familiar programming language such as TypeScript, Python, or Go.

In this tutorial, you will provision an EC2 instance on AWS using TypeScript. This tuturial is also available in Python and Go editions.

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+
• CDK for Terraform v0.8+
• Node.js v12.16+
• an AWS account and AWS Access Credentials
• 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.

»Initialize a new CDK for Terraform application

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

$ mkdir learn-cdktf-typescript

$ mkdir learn-cdktf-typescript

Then navigate into it.

$ cd learn-cdktf-typescript

$ cd learn-cdktf-typescript

Inside the directory, run cdktf init with the TypeScript template. Use --local to store Terraform's state file on your machine instead of remotely in Terraform Cloud. This will initialize a brand new CDK for Terraform project in TypeScript using an interactive command. Accept the defaults when prompted.

$ cdktf init --template="typescript" --local
Note: By supplying '--local' option you have chosen local storage mode for storing the state of your stack.
This means that your Terraform state file will be stored locally on disk in a file 'terraform.<STACK NAME>.tfstate' in the root of your project.
? projectName: learn-cdktf-typescript
? projectDescription: A simple getting started project for cdktf.
## ...
 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" --localNote: By supplying '--local' option you have chosen local storage mode for storing the state of your stack.This means that your Terraform state file will be stored locally on disk in a file 'terraform.<STACK NAME>.tfstate' in the root of your project.? projectName: learn-cdktf-typescript? projectDescription: A simple getting started project for cdktf.## ... 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 provides pre-built classes for several common Terraform providers that you can use in your TypeScript projects. For other Terraform providers, use cdktf get to generate the appropriate TypeScript classes.

»Install AWS provider

Install the AWS provider with npm.

$ npm install @cdktf/provider-aws
+ @cdktf/provider-aws@2.0.13
added 1 package from 1 contributor and audited 391 packages in 4.328s

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

found 0 vulnerabilities

$ npm install @cdktf/provider-aws+ @cdktf/provider-aws@2.0.13added 1 package from 1 contributor and audited 391 packages in 4.328s
29 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 snippet. This new TypeScript application uses the CDK to provision an EC2 instance in us-west-1.

import { Construct } from "constructs";
import { App, TerraformStack, TerraformOutput } 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();
new MyStack(app, "typescript-aws");
app.synth();

import { Construct } from "constructs";import { App, TerraformStack, TerraformOutput } 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();new MyStack(app, "typescript-aws");app.synth();

»Examine the code

Most of the code is similar to concepts you've found in a traditional Terraform configuration written in HCL, but there are a few notable differences. Let's look at each.

Unlike HCL, your TypeScript code must explicitly import any classes it uses. A major addition is TerraformOutput, which you will use to print attributes of the resources that you create.

import { App, TerraformStack, TerraformOutput } from "cdktf";

import { App, TerraformStack, TerraformOutput } from "cdktf";

You must explicitly import the AWS provider and other resources before you use them. In this case you will need the AwsProvider and ec2 classes for your compute resource.

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

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

Next, the example code defines a new stack, which contains 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);

Next, the code configures the AWS provider.

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

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

You can configure the AwsProvider by passing in an object with keys and values that map to Terraform arguments as listed in the provider API. In the snippet below, the region key is set to us-west-1.

Next, 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 instance is also configured with an object, using camel case for properties that correspond to the Terraform API.

If you want to reference a resource, you must store the resource in a variable. In this example, since the TerraformOutput below uses the instance's publicIp attribute, the code stores the instance in a variable named instance.

The public_ip output references the instance variable to return the instance's public IP address.

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

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

Terraform outputs allow you to share values between Terraform workspaces.

When writing this code, you can use IntelliSense to view all the properties of the instance variable. In this case, publicIp is the only one that is used.

»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. Remember to confirm the deploy with a yes.

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


Summary: 1 created, 0 updated, 0 destroyed.

Output: public_ip = 13.52.75.197

$ cdktf deployDeploying Stack: typescript-awsResources ✔ AWS_INSTANCE        compute             aws_instance.compute

Summary: 1 created, 0 updated, 0 destroyed.
Output: public_ip = 13.52.75.197

The cdktf deploy command runs terraform apply in the background. If you are using local storage mode, the command creates a terraform.tfstate file in the root of the project.

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

Notice that the CDK's deploy output (public_ip) matches the instance's public IPv4 address.

»Change infrastructure by adding the Name tag

Add a tag to the EC2 instance. Update the Instance in main.ts to the following.

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

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

Deploy your updated application. Remember to confirm your run with a yes.

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

Summary: 0 created, 1 updated, 0 destroyed.

Output: public_ip = 13.52.75.197

$ cdktf deployDeploying Stack: typescript-awsResources ✔ AWS_INSTANCE        compute             aws_instance.compute
Summary: 0 created, 1 updated, 0 destroyed.
Output: public_ip = 13.52.75.197

»Clean up your infrastructure

Destroy the application by running cdktf destroy. Remember to confirm your run with a yes.

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

Summary: 1 destroyed.

$ cdktf destroyDestroying Stack: typescript-awsResources ✔ AWS_INSTANCE         compute             aws_instance.compute
Summary: 1 destroyed.

»Next steps

Congrats, you 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 standard terraform executable to provision infrastructure using terraform apply and other Terraform commands.
• Use any Terraform provider by adding it to terraformProviders in cdktf.json and running cdktf get.
• Use Typescript 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 documentation in the terraform-cdk repository. In particular, check out the:

• Getting started guides.
• Feature documentation.
• Example code in several programming languages.