Now that you've installed cdktf, you will use it to deploy an AWS EC2 instance using Python.
»Prerequisites
To follow this tutorial, you need the following instaled locally:
Terraform v0.12+
Node.js v12.16+
an AWS account and AWS Access Credentials
If you don't have AWS Access Credentials, create your AWS Access Key ID and Secret Access Key by navigating to your service credentials in the IAM service on AWS. Click "Create access key" here to view your
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY.
Terraform and the cdktf tool will use credentials set in your environment or through other means as described in the Terraform documentation. This tutorial will assume you are using the "Environment Variables" method.
Add your AWS credentials as two environment variables, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, replacing AAAAAA with each respective values.
$ export AWS_ACCESS_KEY_ID=AAAAAA
$ export AWS_SECRET_ACCESS_KEY=AAAAA
»Initialize a new CDK for Terraform application
Create a folder named hello-terraform.
$ mkdir hello-terraform
Then navigate into it.
$ cd hello-terraform
Initialize a new CDK for Terraform application in Python. The cdk init command will populate the directory with boilerplate files and install the cdktf library so that the project can use it.
Choose one of the two available Python templates.
- The
pythontemplate usespipenvfor package management - The
python-piptemplate usespipwith a simplerequirements.txtfile.
$ cdktf init --template="python" --local
The command will ask you to specify a project name and description. Use the default values by pressing the Enter key.
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.tfstate' in the root of your project.
We will now set up the project. Please enter the details for your project.
If you want to exit, press ^C.
Project Name: (default: 'hello-terraform')
Project Description: (default: 'A simple getting started project for cdktf.')
If you run into the following errors, you did not install cdktf correctly or you may be using the wrong Python version. Verify that python and pip is set to Python 3.7+.
Error: Command failed: pipenv install cdktf~=0.0.17-pre.f718c5d1f6c8397df97f5f9bdb8c4f0d771adc17
»Define your CDK for Terraform Application
Open the main.py file. This file contains generic CDK for Terraform application code.
#!/usr/bin/env python
from constructs import Construct
from cdktf import App, TerraformStack
class MyStack(TerraformStack):
def __init__(self, scope: Construct, ns: str):
super().__init__(scope, ns)
# define resources here
app = App()
MyStack(app, "hello-terraform")
app.synth()
Replace the contents of main.py with the following code snippet.
This new Python application uses the CDK to provision an EC2 instance to us-east-1.
#!/usr/bin/env python
from constructs import Construct
from cdktf import App, TerraformStack, TerraformOutput
from imports.aws import Instance, AwsProvider
class MyStack(TerraformStack):
def __init__(self, scope: Construct, ns: str):
super().__init__(scope, ns)
AwsProvider(self, 'Aws', region='us-east-1')
helloInstance = Instance(self, 'hello',
ami="ami-2757f631",
instance_type="t2.micro",
)
TerraformOutput(self, 'hello_public_ip',
value=helloInstance.public_ip
)
app = App()
MyStack(app, "hello-terraform")
app.synth()
»Synthesize CDK for Terraform application
Run the synthesize command to generate Terraform JSON configuration for the application.
$ cdktf synth
Generated Terraform code in the output directory: cdktf.out
This command will generate a directory called cdktf.out containing the Terraform JSON configuration for the application. You can use Terraform commands like terraform init, terraform plan, and terraform apply with the generated Terraform JSON configuration or optionally continue to use the CDK for Terraform CLI for a first-class experience.
View the contents of cdktf.out/cdk.json. This file contains Terraform configuration defining the AWS provider and the EC2 instance configuration described in your Python code above, expressed as Terraform JSON configuration.
$ cat cdktf.out/cdk.json
{
"terraform": {
"required_providers": {
"aws": "~> 2.0"
}
},
"provider": {
"aws": [
{
"region": "us-east-1"
}
]
},
"resource": {
"aws_instance": {
"examplepythonhello3532B955": {
"ami": "ami-2757f631",
"instance_type": "t2.micro"
}
}
}
}
»Deploy CDK for Terraform application
There are two ways to deploy your Terraform Stack using cdktf.
- You can deploy your Terraform stack using the
cdktf deploycommand. - You can navigate into
cdktf.outand deploy your application using the Terraform CLI workflow (terraform init,terraform plan, andterraform apply)
Deploy your CDK for Terraform application using the cdktf deploy command. This command will ask for confirmation on a generated diff and then deploy the application.
Confirm the run with a yes.
$ cdktf deploy
Stack: hello-terraform
Resources
+ AWS_INSTANCE hello aws_instance.helloterraform_hello_A790281A
Diff: 1 to create, 0 to update, 0 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:
Your terminal will update to the following once the apply completes.
$ cdktf deploy
Deploying Stack: hello-terraform
Resources
✔ AWS_INSTANCE hello aws_instance.helloterraform_hello_A790281A
Summary: 1 created, 0 updated, 0 destroyed.
Output: helloterraform_hellopublicip_83F31665 = 54.146.73.24
The cdktf deploy command runs terraform apply in the background. If you are using local storage mode then it creates a terraform.tfstate file in the root of the project.
»Change infrastructure by adding the Name tag
Add a tag to the EC2 instance. The "Name" tag will be displayed in the AWS Console for easier readability. Update the helloInstance variable in main.py to the following.
helloInstance = Instance(self, 'hello',
ami="ami-2757f631",
instance_type="t2.micro",
+ tags={"Name":"Provisioned by Python"}
)
Deploy your application. Remember to confirm your run with a yes.
$ cdktf deploy
Stack: hello-terraform
Resources
- AWS_INSTANCE hello aws_instance.helloterraform_hello_A790281A
Diff: 0 to create, 1 to update, 0 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:
Once the apply completes, verify that the tag was added to your instance by going to your AWS EC2 Dashboard.
»Destroy CDK for Terraform application
Destroy the application by running cdktf destroy. Remember to confirm your run with a yes.
$ cdktf destroy
Stack: hello-terraform
Resources
- AWS_INSTANCE hello aws_instance.helloterraform_hello_A790281A
Diff: 0 to create, 0 to update, 1 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:
Your terminal will update to the following once the destroy step completes.
Destroying Stack: helloterraform
Resources
✔ AWS_INSTANCE hello aws_instance.helloterraform_hello_A790281A
Summary: 1 destroyed.
»Next steps
Even in its current state of development, cdktf is capable of much more. The synth command will generate JSON which can be used by the standard terraform executable to provision infrastructure using terraform apply and related commands.
Any other Terraform provider can be used by listing it under terraformProviders in cdktf.json and running cdktf get.
Python language features can be used to build configuration around class inheritance or to fetch data from other sources which can be used together with your Terraform configuration.
Or, you can use cdktf with Terraform Cloud for persistent storage of your state file and for team collaboration.
For other examples, see the documentation in the terraform-cdk repository.