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

Terraform >= v1.0+
Node.js >= v14+
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.

»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@latest

$ npm install --global cdktf-cli@latest

»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 init [OPTIONS]             Create a new cdktf project from a template.
  cdktf get [OPTIONS]              Generate CDK Constructs for Terraform providers and modules.
  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 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
  cdktf completion                 generate completion script

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 init [OPTIONS]             Create a new cdktf project from a template.  cdktf get [OPTIONS]              Generate CDK Constructs for Terraform providers and modules.  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 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  cdktf completion                 generate completion script
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]
  -a, --app                       Command to use in order to execute cdktf app                                               [required]
  -o, --output                    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]  -a, --app                       Command to use in order to execute cdktf app                                               [required]  -o, --output                    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.
npm notice created a lockfile as package-lock.json. You should commit this file.
+ constructs@10.0.10
+ cdktf@0.8.1
added 51 packages from 26 contributors and audited 51 packages in 1.78s
## ...

$ 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.npm notice created a lockfile as package-lock.json. You should commit this file.+ constructs@10.0.10+ cdktf@0.8.1added 51 packages from 26 contributors and audited 51 packages in 1.78s## ...

Next, install the Docker provider for cdktf.

$ npm install @cdktf/provider-docker
## ...

+ @cdktf/provider-docker@0.4.41
added 1 package from 1 contributor and audited 418 packages in 5.243s

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

found 0 vulnerabilities

$ npm install @cdktf/provider-docker## ...
+ @cdktf/provider-docker@0.4.41added 1 package from 1 contributor and audited 418 packages in 5.243s
28 packages are looking for funding  run `npm fund` for details
found 0 vulnerabilities

»Edit the code

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 "@cdktf/provider-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 "@cdktf/provider-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();

»Deploy container

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 running docker ps to find the container.

$ 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 remove the container and image, 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, Python, or Go.

Infrastructure

Security

Applications

Networking

cloud