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.2+
• An HCP Terraform account, with CLI authentication configured
• CDK for Terraform v0.15+
• 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.

Go v1.16

Initialize a new CDK for Terraform application

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

$ mkdir learn-cdktf

Then navigate into it.

$ cd learn-cdktf

Inside the directory, run cdktf init, specifying the template for your preferred language and Terraform's AWS provider. Select your HCP Terraform Organization when prompted, and use the default name learn-cdktf for your HCP Terraform Workspace. CDKTF will also prompt you for other information about your project, such as the name and description. Accept the defaults for these options.

$ cdktf init --template="go" --providers="aws@~>4.0"
? 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.
? Do you want to send crash reports to the CDKTF team? See
https://www.terraform.io/cdktf/create-and-deploy/configuration-file#enable-crash
-reporting-for-the-cli for more information Yes

Generating Terraform Cloud configuration for '<YOUR_ORG>' organization and 'learn-cdktf' workspace.....
go: downloading github.com/hashicorp/terraform-cdk-go/cdktf v0.12.0
go: upgraded github.com/aws/constructs-go/constructs/v10 v10.0.25 => v10.1.56
========================================================================================================

  Your cdktf go project is ready!

  cat help                Prints this message

  Compile:
    go build              Builds your go project

  Synthesize:
    cdktf synth [stack]   Synthesize Terraform resources to cdktf.out/

  Diff:
    cdktf diff [stack]    Perform a diff (terraform plan) for the given stack

  Deploy:
    cdktf deploy [stack]  Deploy the given stack

  Destroy:
    cdktf destroy [stack] Destroy the given stack

  Learn more about using modules and providers https://cdk.tf/modules-and-providers

Use Providers:

  Use the add command to add providers:

  cdktf provider add "aws@~>3.0" null kreuzwerker/docker

  Learn more: https://cdk.tf/modules-and-providers

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

Checking whether pre-built provider exists for the following constraints:
  provider: aws
  version : ~>4.0
  language: go
  cdktf   : 0.15.0

Found pre-built provider.
Package installed.

CDKTF provides packages with prebuilt classes for each supported programming language for many common Terraform providers that you can use in your CDKTF projects. The cdktf init command you just ran will find a pre-built AWS provider that you will use for this project. For other Terraform providers and modules, CDKTF automatically generates the appropriate classes for your chosen language.

Define your CDK for Terraform Application

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

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

package main

import (
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    "github.com/hashicorp/terraform-cdk-go/cdktf"

    "github.com/cdktf/cdktf-provider-aws-go/aws/v10/instance"
    awsprovider "github.com/cdktf/cdktf-provider-aws-go/aws/v10/provider"
)

func NewMyStack(scope constructs.Construct, id string) cdktf.TerraformStack {
    stack := cdktf.NewTerraformStack(scope, &id)

    awsprovider.NewAwsProvider(stack, jsii.String("AWS"), &awsprovider.AwsProviderConfig{
        Region: jsii.String("us-west-1"),
    })

    instance := instance.NewInstance(stack, jsii.String("compute"), &instance.InstanceConfig{
        Ami:          jsii.String("ami-01456a894f71116f2"),
        InstanceType: jsii.String("t2.micro"),
    })

    cdktf.NewTerraformOutput(stack, jsii.String("public_ip"), &cdktf.TerraformOutputConfig{
        Value: instance.PublicIp(),
    })

    return stack
}

func main() {
    app := cdktf.NewApp(nil)
    stack := NewMyStack(app, "aws_instance")
    cdktf.NewRemoteBackend(stack, &cdktf.RemoteBackendProps{
        Hostname:     jsii.String("app.terraform.io"),
        Organization: jsii.String("<YOUR_ORG>"),
        Workspaces:   cdktf.NewNamedRemoteWorkspace(jsii.String("learn-cdktf")),
    })

    app.Synth()
}

Replace <YOUR_ORG> with the HCP Terraform organization name you chose when you ran terraform init earlier. If you chose a different workspace name, replace learn-cdktf with that name.

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 declare a package name and import any packages your Go code uses. For example, you will use NewTerraformOutput from the cdktf package to create a Terraform output value for your EC2 instance's public IP address.

The example code imports the AWS provider and other resources from the package you installed earlier. In this case you need the provider and instance classes from the AWS provider for your compute resource. The code uses an alias to rename the provider to awsprovider. You can use this pattern when you use multiple providers to give each one a unique name.

package main

import (
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    "github.com/hashicorp/terraform-cdk-go/cdktf"

    "github.com/cdktf/cdktf-provider-aws-go/aws/v10/instance"
    awsprovider "github.com/cdktf/cdktf-provider-aws-go/aws/v10/provider"
)

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

func NewMyStack(scope constructs.Construct, id string) cdktf.TerraformStack {
    stack := cdktf.NewTerraformStack(scope, &id)

The code configures the AWS provider to use the us-west-1 region. In this code, the strings "AWS" and "us-west-1" are being passed to the jsii.String() function. Go does not support nullable types, while CDK uses null values to represent optional arguments. Jsii provides helper functions such as jsii.String() to convert Go data types into pointers, which can be nil if no value is set.

    awsprovider.NewAwsProvider(stack, jsii.String("AWS"), &awsprovider.AwsProviderConfig{
        Region: jsii.String("us-west-1"),
    })

The provider accepts an object with keys and values that map to Terraform arguments as listed in the AWS provider documentation.

The ec2.NewInstance function creates a t2.micro EC2 instance with an AWS ami.

    instance := instance.NewInstance(stack, jsii.String("compute"), &instance.InstanceConfig{
        Ami:          jsii.String("ami-01456a894f71116f2"),
        InstanceType: jsii.String("t2.micro"),
    })

The code also configures the instance with an object, ec2.InstanceConfig, 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() method.

    cdktf.NewTerraformOutput(stack, jsii.String("public_ip"), &cdktf.TerraformOutputConfig{
        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() method from the instance variable.

Finally, in the main() function creates your application using the stack you have defined, configures a remote backend to store your project's state in HCP Terraform, and calls app.Synth() to generate Terraform configuration.

func main() {
    app := cdktf.NewApp(nil)
    stack := NewMyStack(app, "aws_instance")

    cdktf.NewRemoteBackend(stack, &cdktf.RemoteBackendProps{
        Hostname:     jsii.String("app.terraform.io"),
        Organization: jsii.String("<YOUR_ORG>"),
        Workspaces:   cdktf.NewNamedRemoteWorkspace(jsii.String("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

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.NewInstance in main.go to add a Name tag.

    instance := instance.NewInstance(stack, jsii.String("compute"), &instance.InstanceConfig{
    Ami:          jsii.String("ami-01456a894f71116f2"),
    InstanceType: jsii.String("t2.micro"),
    Tags: &map[string]*string{
      "Name": jsii.String("CDKTF-Demo"),
    },
  })

Deploy your updated application. Confirm your deploy by choosing Approve.

$ cdktf deploy
aws_instance  Initializing the backend...
aws_instance
              Successfully configured the backend "remote"! Terraform will automatically
              use this backend unless the backend configuration changes.
aws_instance  Initializing provider plugins...
aws_instance  - Finding hashicorp/aws versions matching "4.23.0"...
aws_instance  - Using hashicorp/aws v4.23.0 from the shared cache directory
##...
              Plan: 1 to add, 0 to change, 0 to destroy.

              Changes to Outputs:
              + public_ip = (known after apply)
aws_instance
              ─────────────────────────────────────────────────────────────────────────────

              Saved the plan to: plan

              To perform exactly these actions, run the following command to apply:
              terraform apply "plan"

Please review the diff output above for aws_instance
❯ Approve  Applies the changes outlined in the plan.
  Dismiss
  Stop
##...
              Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

              Outputs:


aws_instance  public_ip = "54.219.167.18"

  aws_instance
  public_ip = 54.219.167.18

Clean up your infrastructure

Destroy the application by running cdktf destroy. Confirm your destroy by choosing Approve.

$ cdktf destroy
aws_instance  Initializing the backend...
aws_instance  Initializing provider plugins...
              - Reusing previous version of hashicorp/aws from the dependency lock file
aws_instance  - Using previously-installed hashicorp/aws v4.23.0
##...
              Plan: 0 to add, 0 to change, 1 to destroy.

              Changes to Outputs:
              - public_ip = "54.219.167.18" -> null
aws_instance
              ─────────────────────────────────────────────────────────────────────────────

              Saved the plan to: plan

              To perform exactly these actions, run the following command to apply:
              terraform apply "plan"

Please review the diff output above for aws_instance
❯ Approve  Applies the changes outlined in the plan.
  Dismiss
  Stop
##...
              Plan: 0 to add, 0 to change, 1 to destroy.

              Changes to Outputs:
              - public_ip = "54.219.167.18" -> null
aws_instance  aws_instance.compute (compute): Destroying... [id=i-0fc8d2e3931b28db3]
aws_instance  aws_instance.compute (compute): Still destroying... [id=i-0fc8d2e3931b28db3, 10s elapsed]
aws_instance  aws_instance.compute (compute): Still destroying... [id=i-0fc8d2e3931b28db3, 20s elapsed]
aws_instance  aws_instance.compute (compute): Still destroying... [id=i-0fc8d2e3931b28db3, 30s elapsed]
aws_instance  aws_instance.compute (compute): Destruction complete after 30s
aws_instance
              Destroy complete! Resources: 1 destroyed.

Destroying your CDKTF application will not remove the HCP Terraform workspace that stores your project's state. Log into the HCP Terraform 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 HCP Terraform 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.