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.
See 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.
You can use npm
to install cdktf.
Because cdktf is being constantly improved, we recommend keeping up to date with the cutting edge development version by using the @next
tag.
$ 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
Create the project from scratch, starting with a directory named typescript-docker
.
$ mkdir typescript-docker && cd $_
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 container within Docker.
$ cdktf deploy
Stack: typescript-docker
Resources
+ DOCKER_CONTAINER nginxContainer docker_container.
+ DOCKER_IMAGE nginxImage docker_image.
Diff: 2 to create, 0 to update, 0 to delete.
Do you want to continue (Y/n)?
Verify the existence of the NGINX container by visiting localhost:8000 in your web browser or run docker ps
to see 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
.
$ cdktf destroy
Stack: typescript-docker
Resources
- DOCKER_CONTAINER nginxContainer docker_container.
- DOCKER_IMAGE nginxImage docker_image.
Diff: 0 to create, 0 to update, 2 to delete.
Do you want to continue (Y/n)?
You've now provisioned and destroyed an NGINX webserver with cdktf
.