Build AWS Infrastructure with Python

CDK for Terraform (CDKTF) allows you to define your infrastructure in a familiar programming language such as TypeScript, Python, or Go.

In this tutorial, you will provision an EC2 instance on AWS using Python. This tuturial is also available in TypeScript and Go editions.

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 v0.15+
• CDK for Terraform
• Node.js v12.16+
• Python v3.7+ and pipenv
• an AWS account and AWS Access Credentials

Terraform and CDKTF 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.

1. Set your AWS_ACCESS_KEY_ID replacing AAAAAA with your AWS Access Key ID.

$ export AWS_ACCESS_KEY_ID=AAAAAA

1. Set your AWS_SECRET_ACCESS_KEY replacing AAAAAA with your AWS Secret Access Key.

$ export AWS_SECRET_ACCESS_KEY=AAAAA

»Initialize a new CDK for Terraform application

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

$ mkdir learn-cdktf-python

Then navigate into it.

$ cd learn-cdktf-python

Initialize a new CDK for Terraform application in Python. The cdktf 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.

1. The python template uses the newer pipenv command for package management.
2. The python-pip template uses the built-in pip command.

$ cdktf init --template="python" --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.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: 'learn-cdktf-python') 
Project Description: (default: 'A simple getting started project for cdktf.') 
Pipfile.lock not found, creating...
Locking [dev-packages] dependencies...
Locking [packages] dependencies...
Updated Pipfile.lock (c0c5a6)!
Installing dependencies from Pipfile.lock (c0c5a6)...
## ...

If you run into the following error, 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

»Add AWS provider

Open cdktf.json in your text editor, and add aws as one of the Terraform providers that you will use in the application.

 {
   "language": "python",
   "app": "pipenv run python main.py",
-  "terraformProviders": [],
+  "terraformProviders": [
+    "hashicorp/aws@~> 3.42"
+  ],
   "terraformModules": [],
   "codeMakerOutput": "imports",  
   "context": {
     "excludeStackIdFromLogicalIds": "true",
     "allowSepCharsInLogicalIds": "true"
   }
 }

Run cdktf get to install the AWS provider you added to cdktf.json.

$ cdktf get
Generated python constructs in the output directory: imports

»Define your CDK for Terraform Application

Open the main.py file to view your application code. The template creates a scaffold with no functionality.

Replace the contents of main.py with the following code snippet. This new Python application uses the CDK to provision an EC2 instance in us-west-1.

#!/usr/bin/env python
from constructs import Construct
from cdktf import App, TerraformStack, TerraformOutput
from imports.aws import AwsProvider, Instance


class MyStack(TerraformStack):
  def __init__(self, scope: Construct, ns: str):
    super().__init__(scope, ns)

    AwsProvider(self, 'Aws', region='us-west-1')

    helloInstance = Instance(self, 'hello',
      ami="ami-01456a894f71116f2",
      instance_type="t2.micro",
    )

    TerraformOutput(self, 'hello_public_ip',
      value=helloInstance.public_ip
    )

app = App()
MyStack(app, "hello-terraform")

app.synth()

»Examine the code

Most of the code is similar to concepts you've found in a traditional Terraform configuration written in HCL, but there are a few notable differences. Let's look at each.

Unlike HCL, your Python code must explicitly import any classes it uses. A major addition is TerraformOutput, which you will use to print attributes of the resources that you create.

from cdktf import App, TerraformStack, TerraformOutput

You must explicitly import the AWS provider and other resources before you use them. In this case you will need the AwsProvider and Instance classes for your compute resource.

from imports.aws import AwsProvider, Instance

Next, the example code defines a new stack, which contains code to define your provider and all of your resources.

class MyStack(TerraformStack):
  def __init__(self, scope: Construct, ns: str):
    super().__init__(scope, ns)

Next, the code configures the AWS provider.

    AwsProvider(self, 'Aws', region='us-west-1')

You can configure the AwsProvider by passing in named arguments that map to Terraform arguments as listed in the provider API. In the snippet below, the region key is set to us-west-1.

Next, the code defines a compute instance with the Instance class.

    helloInstance = Instance(self, 'hello',
      ami="ami-01456a894f71116f2",
      instance_type="t2.micro",
    )

For this, you'll also use camel case for properties that correspond to the Terraform API.

If you want to reference a resource, you must store the resource in a variable. In this example, since the TerraformOutput below uses the instance's publicIp attribute, the code stores the instance in a variable named helloInstance.

The hello_public_ip output references the helloInstance variable to return the instance's public IP address.

    TerraformOutput(self, 'hello_public_ip',
      value=helloInstance.public_ip
    )

Terraform outputs allow you to share values between Terraform workspaces.

»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. Remember to confirm the deploy with a yes.

$ cdktf deploy
Deploying Stack: hello-terraform
Resources
 ✔ AWS_INSTANCE        hello               aws_instance.hello


Summary: 1 created, 0 updated, 0 destroyed.

Output: hello_public_ip = 3.208.25.25

The cdktf deploy command runs terraform apply in the background. If you are using local storage mode, the command creates a terraform.tfstate file in the root of the project.

After the instance is created, visit the AWS EC2 Dashboard.

Notice that the CDK's deploy output (public_ip) matches the instance's public IPv4 address.

»Change infrastructure by adding the Name tag

Add a tag to the EC2 instance. Update the Instance in main.py to the following.

 helloInstance = Instance(self, 'hello',
   ami="ami-01456a894f71116f2",
   instance_type="t2.micro",
+  tags={"Name": "Python-Demo"},
 )

Deploy your updated application. Remember to confirm your run with a yes.

$ cdktf deploy
Deploying Stack: hello-terraform
Resources
 ✔ AWS_INSTANCE        hello               aws_instance.hello


Summary: 0 created, 1 updated, 0 destroyed.

Output: hello_public_ip = 3.208.25.25

»Clean up your infrastructure

Destroy the application by running cdktf destroy. Remember to confirm your run with a yes.

$ cdktf destroy
Destroying Stack: hello-terraform
Resources
 ✔ AWS_INSTANCE        hello               aws_instance.hello


Summary: 1 destroyed.

»Next steps

Congrats, you 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 standard terraform executable to provision infrastructure using terraform apply and other Terraform commands.
• Use any Terraform provider by adding it to terraformProviders in cdktf.json and running cdktf get.
• Use Python 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 documentation in the terraform-cdk repository. In particular, check out the:

• Getting started guides.
• Feature documentation.
• Example code in several programming languages.