Install cdktf and Run a Quick Start Demo

To use cdktf you will need to install it. The tool is available as a Typescript application from npm.

»Prerequisites

In order to use cdktf, you'll need Terraform, Node.js, and Yarn.

• Terraform >= v0.12
• Node.js >= v12.16
• Yarn >= v1.21
• Docker

Refer to the Terraform install tutorial for instructions on installing Terraform via package manager, source, or binary download.

Node.js publishes a graphical installer that will install Node.js and npm on your platform.

Yarn is an alternate JavaScript package manager that can be installed via Homebrew, precompiled binary, or from source.

»Install cdktf

There are two ways to install cdktf.

$ npm install --global cdktf-cli@next

»Verify the installation

Verify that the installation worked by opening a new terminal session and running the cdktf command to show available subcommands.

$ cdktf

cdktf [command]

Commands:
  cdktf deploy [OPTIONS]   Deploy the given stack
  cdktf destroy [OPTIONS]  Destroy the given stack
  cdktf diff [OPTIONS]     Perform a diff (terraform plan) for the given stack
  cdktf get [OPTIONS]      Generate CDK Constructs for Terraform providers and modules.
  cdktf init [OPTIONS]     Create a new cdktf project from a template.
  cdktf login              Retrieves an API token to connect to Terraform Cloud.
  cdktf synth [OPTIONS]    Synthesizes Terraform code for the given app in a directory.

Add --help to any subcommand to learn more about what it does and available options.

$ cdktf deploy --help

»Quick start tutorial

Now that you've installed cdktf, you can write TypeScript code that will provision an NGINX server using Docker on Mac, Windows, or Linux. This example is free and requires no cloud credentials to run.

If you have cdktf and Docker installed on your local machine, start Docker Desktop by launching the application in your file browser or by running this command in a macOS terminal.

$ open -a Docker

»Create and initialize the project

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

$ mkdir typescript-docker

Then navigate into it.

$ cd typescript-docker

Initialize the project with the init command. For this quick start, use the --local flag so that all state will be stored locally.

$ cdktf init --template=typescript --local

You'll be prompted for a project name and description. You can use the defaults as listed.

»Edit the code

Add code to two files: cdktf.json and main.ts.

In cdktf.json, list docker as one of the Terraform providers that you'll be using in the application. You can replace the existing "aws" example in the file.

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformProviders": [
-   "aws@~> 2.0"
+   "terraform-providers/docker@~> 2.0"
  ]
}

Delete the contents of main.ts and paste the following TypeScript code into the main.ts file. We've included the equivalent HCL configuration in a tab for comparison.

import { Construct } from 'constructs'
import { App, TerraformStack } from 'cdktf'
import { Container, Image, DockerProvider } from './.gen/providers/docker'

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

    new DockerProvider(this, 'default', {})

    const dockerImage = new Image(this, 'nginxImage', {
      name: 'nginx:latest',
      keepLocally: false,
    })

    new Container(this, 'nginxContainer', {
      image: dockerImage.latest,
      name: 'tutorial',
      ports: [
        {
          internal: 80,
          external: 8000,
        },
      ],
    })
  }
}

const app = new App()
new MyStack(app, 'typescript-docker')
app.synth()

»Install dependencies and deploy

You're almost there! Run the get command to download the dependencies for using Docker with Typescript.

$ cdktf get

Now run deploy to compile the code and provision the NGINX Docker container. Remember to confirm the deploy with a yes.

$ cdktf deploy
Stack: typescript-docker
Resources
 + DOCKER_CONTAINER     nginxContainer      docker_container.nginxContainer
 + DOCKER_IMAGE         nginxImage          docker_image.nginxImage

Diff: 2 to create, 0 to update, 0 to delete.

Verify the existence of the NGINX container by visiting localhost:8000 in your web browser or run docker ps to find the container.

$ docker ps

CONTAINER ID        IMAGE                     COMMAND                  CREATED             STATUS              PORTS                    NAMES
425d5ee58619        e791337790a6              "nginx -g 'daemon of…"   20 seconds ago      Up 19 seconds       0.0.0.0:8000->80/tcp     tutorial

»Destroy the container

To stop the container, run cdktf destroy. Remember to confirm the destroy with a yes.

$ cdktf destroy
Stack: typescript-docker
Resources
 - DOCKER_CONTAINER     nginxContainer      docker_container.nginxContainer
 - DOCKER_IMAGE         nginxImage          docker_image.nginxImage

Diff: 0 to create, 0 to update, 2 to delete.

Do you want to perform these actions?
 CDK for Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

You've now provisioned and destroyed an NGINX webserver with cdktf.