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.0+
- A Terraform Cloud account, with CLI authentication configured
- CDK for Terraform v0.8+
- 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.
Typescript v4.4 and Node.js v16.13
»Initialize a new CDK for Terraform application
Start by creating a directory named learn-cdktf
for your project.
Then navigate into it.
Inside the directory, run cdktf init
, specifying the template for your
preferred language.
Tip: If you would prefer to keep your state locally, use the --local
flag with cdktf init
.
This will initialize a brand new CDK for Terraform project using an interactive
command. Accept the defaults for "Project Name" and "Project Description". Select
your Terraform Cloud Organization, and choose the name learn-cdktf
for the Terraform Cloud Workspace.
»Install AWS provider
CDKTF provides packages with prebuilt classes for several common Terraform
providers that you can use in your TypeScript projects. For other Terraform
providers and modules, you can add them to cdktf.json
and use cdktf get
to
generate the appropriate TypeScript
classes.
Install the AWS provider with npm
.
»Define your CDK for Terraform Application
Open the main.ts
file to view your application code. The template creates a
scaffold with no functionality.
Replace the contents of main.ts
with the following code for a new TypeScript
application, which uses the CDK to provision an AWS EC2 instance in us-west-1
,
and stores its state in Terraform Cloud.
Replace <YOUR_ORG>
with the Terraform Cloud organization name you chose when
you ran terraform init
earier.
Tip: If you would prefer to store your project's state locally, remove or
comment out new RemoteBackend(stack, { [...] });
and remove RemoteBackend
from the import { [...] } from "cdktf";
line near the top of the file.
»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 import any classes your TypeScript code uses. For example,
you will use TerraformOutput
to create a Terraform output value for your EC2
instance's public IP address.
The code imports the AwsProvider
and ec2
classes from the provider you
installed earlier with npm install
.
The example code defines a new stack, which contains the code to define your provider and all of your resources.
The code configures the AWS provider to use the us-west-1
region.
The example code configures the AwsProvider
by passing in an object with keys
and values that map to Terraform arguments as listed in the AWS provider
documentation.
The code defines a compute instance with the ec2.Instance
class.
The code also configures the instance with an object, 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
attribute.
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
attribute from the instance
variable.
Finally, the example code creates your application using the stack you have
defined, configures a remote backend to store your project's state in Terraform
Cloud, and runs app.synth()
to generate Terraform configuration.
»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
.
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.Instance
in main.ts
to add a Name
tag.
Deploy your updated application. Confirm your deploy with a yes
.
»Clean up your infrastructure
Destroy the application by running cdktf destroy
. Confirm your run with a
yes
.
Destroying your CDKTF application will not remove the Terraform Cloud workspace that stores your project's state. If you don't want to run this example again, log into the Terraform Cloud 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 usingterraform 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 Terraform Cloud 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.