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

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

Add your AWS credentials as two environment variables.

1. Set your AWS_ACCESS_KEY_ID replacing AAAAAA with your AWS Access Key ID.

$ export AWS_ACCESS_KEY_ID=AAAAAA

$ export AWS_ACCESS_KEY_ID=AAAAAA

1. Set your AWS_SECRET_ACCESS_KEY replacing AAAAAA with your AWS Secret Access Key.

$ export AWS_SECRET_ACCESS_KEY=AAAAA

$ export AWS_SECRET_ACCESS_KEY=AAAAA

»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.

$ 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.tfstate' in the root of your project.

We will now set up the project. Please enter the details for your project.
If you want to exit, press ^C.

Project Name: (default: 'learn-cdktf-typescript') 
Project Description: (default: 'A simple getting started project for cdktf.') 

## ...

$ 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.tfstate' in the root of your project.
We will now set up the project. Please enter the details for your project.If you want to exit, press ^C.
Project Name: (default: 'learn-cdktf-typescript') Project Description: (default: 'A simple getting started project for cdktf.') 
## ...

This will initialize a brand new CDK for Terraform project in TypeScript using an interactive command. Accept the defaults when prompted.

»Add AWS provider

Open cdktf.json in your text editor, and add aws as one of the Terraform providers that you use in the application.

 {
   "language": "typescript",
   "app": "npm run --silent compile && node main.js",
-  "terraformProviders": [],
+  "terraformProviders": [
+    "hashicorp/aws@~> 3.42"
+  ],
   "terraformModules": [],
   "context": {
     "excludeStackIdFromLogicalIds": "true",
     "allowSepCharsInLogicalIds": "true"
   }
 }

 {   "language": "typescript",   "app": "npm run --silent compile && node main.js",-  "terraformProviders": [],+  "terraformProviders": [+    "hashicorp/aws@~> 3.42"+  ],   "terraformModules": [],   "context": {     "excludeStackIdFromLogicalIds": "true",     "allowSepCharsInLogicalIds": "true"   } }

Run cdktf get to install the AWS provider you added to cdktf.json.

$ cdktf get
Generated typescript constructs in the output directory: .gen

$ cdktf getGenerated typescript constructs in the output directory: .gen

»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, Instance } from './.gen/providers/aws'

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

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

    const instance = new 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, Instance } from './.gen/providers/aws'
class MyStack extends TerraformStack {  constructor(scope: Construct, id: string) {    super(scope, id)
    new AwsProvider(this, 'aws', {      region: 'us-west-1',    })
    const instance = new 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 Instance classes for your compute resource.

import { AwsProvider, Instance } from './.gen/providers/aws'

import { AwsProvider, Instance } from './.gen/providers/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 Instance class.

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

const instance = new 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 = 50.18.17.102

$ cdktf deployDeploying Stack: typescript-awsResources ✔ 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. 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 Instance(this, 'compute', {
   ami: 'ami-01456a894f71116f2',
   instanceType: 't2.micro',
+  tags: {
+    Name: 'TypeScript-Demo',
+  },
 })

 const instance = new 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 = 50.18.17.102

$ cdktf deployDeploying Stack: typescript-awsResources ✔ 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. 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.