Install cdktf and Run a Quick Start Demo | Terraform

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 will need Terraform, Node.js, and Yarn. This tutorial also uses Docker in a quick start example project.

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

You can install cdktf with npm on most operating system. You can also install cdktf with Homebrew on MacOS.

You can use npm to install cdktf.

To install the most recent stable release of cdktf, use npm install.

$ npm install --global cdktf-cli

$ npm install --global cdktf-cli

»Verify the installation

Verify that you have cdktf installed by running the cdktf help command to show the available subcommands.

$ cdktf help
cdktf

Commands:
  cdktf convert [OPTIONS]          Converts a single file of HCL configuration to CDK for Terraform. Takes the file to be
                                   converted on stdin.
  cdktf deploy [stack] [OPTIONS]   Deploy the given stack                                                     [aliases: apply]
  cdktf destroy [stack] [OPTIONS]  Destroy the given stack
  cdktf diff [stack] [OPTIONS]     Perform a diff (terraform plan) for the given stack                         [aliases: plan]
  cdktf get [OPTIONS]              Generate CDK Constructs for Terraform providers and modules.
  cdktf init [OPTIONS]             Create a new cdktf project from a template.
  cdktf list [OPTIONS]             List stacks in app.
  cdktf login                      Retrieves an API token to connect to Terraform Cloud.
  cdktf synth [stack] [OPTIONS]    Synthesizes Terraform code for the given app in a directory.          [aliases: synthesize]
  cdktf watch [stack] [OPTIONS]    [experimental] Watch for file changes and automatically trigger a deploy

Options:
  --version                   Show version number                                                                    [boolean]
  --disable-logging           Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.   [boolean] [default: true]
  --disable-plugin-cache-env  Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured
                              differently. Supported using the env CDKTF_DISABLE_PLUGIN_CACHE_ENV.  [boolean] [default: false]
  --log-level                 Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL   [string]
  -h, --help                  Show help                                                                              [boolean]

Options can be specified via environment variables with the "CDKTF_" prefix (e.g. "CDKTF_OUTPUT")

$ cdktf helpcdktf
Commands:  cdktf convert [OPTIONS]          Converts a single file of HCL configuration to CDK for Terraform. Takes the file to be                                   converted on stdin.  cdktf deploy [stack] [OPTIONS]   Deploy the given stack                                                     [aliases: apply]  cdktf destroy [stack] [OPTIONS]  Destroy the given stack  cdktf diff [stack] [OPTIONS]     Perform a diff (terraform plan) for the given stack                         [aliases: plan]  cdktf get [OPTIONS]              Generate CDK Constructs for Terraform providers and modules.  cdktf init [OPTIONS]             Create a new cdktf project from a template.  cdktf list [OPTIONS]             List stacks in app.  cdktf login                      Retrieves an API token to connect to Terraform Cloud.  cdktf synth [stack] [OPTIONS]    Synthesizes Terraform code for the given app in a directory.          [aliases: synthesize]  cdktf watch [stack] [OPTIONS]    [experimental] Watch for file changes and automatically trigger a deploy
Options:  --version                   Show version number                                                                    [boolean]  --disable-logging           Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.   [boolean] [default: true]  --disable-plugin-cache-env  Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured                              differently. Supported using the env CDKTF_DISABLE_PLUGIN_CACHE_ENV.  [boolean] [default: false]  --log-level                 Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL   [string]  -h, --help                  Show help                                                                              [boolean]
Options can be specified via environment variables with the "CDKTF_" prefix (e.g. "CDKTF_OUTPUT")

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

$ cdktf deploy --help
cdktf deploy [stack] [OPTIONS]

Deploy the given stack

Positionals:
  stack  Deploy stack which matches the given id only. Required when more than one stack is present in the app        [string]

Options:
  --version                   Show version number                                                                    [boolean]
  --disable-logging           Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.   [boolean] [default: true]
  --disable-plugin-cache-env  Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured
                              differently. Supported using the env CDKTF_DISABLE_PLUGIN_CACHE_ENV.  [boolean] [default: false]
  --log-level                 Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL   [string]
  --app, -a                   Command to use in order to execute cdktf app                                          [required]
  --output, -o                Output directory                                               [required] [default: "cdktf.out"]
  --auto-approve              Auto approve                                                          [boolean] [default: false]
  -h, --help                  Show help                                                                              [boolean]

$ cdktf deploy --helpcdktf deploy [stack] [OPTIONS]
Deploy the given stack
Positionals:  stack  Deploy stack which matches the given id only. Required when more than one stack is present in the app        [string]
Options:  --version                   Show version number                                                                    [boolean]  --disable-logging           Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.   [boolean] [default: true]  --disable-plugin-cache-env  Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured                              differently. Supported using the env CDKTF_DISABLE_PLUGIN_CACHE_ENV.  [boolean] [default: false]  --log-level                 Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL   [string]  --app, -a                   Command to use in order to execute cdktf app                                          [required]  --output, -o                Output directory                                               [required] [default: "cdktf.out"]  --auto-approve              Auto approve                                                          [boolean] [default: false]  -h, --help                  Show help                                                                              [boolean]

»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

$ open -a Docker

»Create and initialize the project

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

$ mkdir learn-cdktf-docker

$ mkdir learn-cdktf-docker

Then, navigate into it.

$ cd learn-cdktf-docker

$ cd learn-cdktf-docker

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 will prompt you for a project name and description. Use the defaults as listed.

$ 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-docker
? projectDescription: A simple getting started project for cdktf.

added 2 packages, and audited 52 packages in 806ms
## ...

$ 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-docker? projectDescription: A simple getting started project for cdktf.
added 2 packages, and audited 52 packages in 806ms## ...

Next, install the Docker provider for cdktf.

$ npm install @cdktf/provider-docker

added 1 package, and audited 55 packages in 2s

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

found 0 vulnerabilities

$ npm install @cdktf/provider-docker
added 1 package, and audited 55 packages in 2s
5 packages are looking for funding  run `npm fund` for details
found 0 vulnerabilities

»Edit the code

Open cdktf.json in your text editor, and add docker as one of the Terraform providers that you'll be using in the application.

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

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

Delete the contents of main.ts and paste the following TypeScript code into it. Click on the "HCL" tab to find the equivalent HCL configuration 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()

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

Run the cdktf get command to download the dependencies for using Docker with Typescript.

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

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

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

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

Summary: 2 created, 0 updated, 0 destroyed.

$ cdktf deployDeploying Stack: typescript-dockerResources ✔ DOCKER_CONTAINER     nginxContainer      docker_container.nginxContainer ✔ DOCKER_IMAGE         nginxImage          docker_image.nginxImage
Summary: 2 created, 0 updated, 0 destroyed.

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

NGINX running in Docker via Terraform

$ docker ps
CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                  NAMES
d572a1770b6c   2622e6cca7eb   "/docker-entrypoint.…"   31 seconds ago   Up 29 seconds   0.0.0.0:8000->80/tcp   tutorial

$ docker psCONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                  NAMESd572a1770b6c   2622e6cca7eb   "/docker-entrypoint.…"   31 seconds ago   Up 29 seconds   0.0.0.0:8000->80/tcp   tutorial

»Destroy the container

To stop the container, run cdktf destroy. This process may take a few minutes, since cdktf waits for your docker container to stop. Remember to confirm the destroy with a yes.

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

Summary: 2 destroyed.

$ cdktf destroyDestroying Stack: typescript-dockerResources ✔ DOCKER_CONTAINER     nginxContainer      docker_container.nginxContainer ✔ DOCKER_IMAGE         nginxImage          docker_image.nginxImage
Summary: 2 destroyed.

You have now provisioned and destroyed an NGINX webserver with cdktf.

»Next steps

Now that you have installed cdktf, learn how to use it to manage your resources using Typescript or Python.

Infrastructure

Security

Networking

Applications