Build AWS Infrastructure with Python | Terraform

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 installed locally:

Terraform v0.12+
cdktf
Node.js v12.16+
Python v3.7+ and pipenv
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_ID and AWS_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

Start by creating a directory named hello-terraform for the project.

$ 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 python template uses pipenv for package management
The python-pip template uses pip with a simple requirements.txt file.

$ 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.

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-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.tf.json. This file defines the AWS provider and EC2 instance configuration described in your Python code above, expressed as Terraform JSON configuration.

$ cat cdktf.out/cdk.tf.json
{
  "//": {
    "metadata": {
      "version": "0.1.0",
      "stackName": "hello-terraform"
    }
  },
  "terraform": {
    "required_providers": {
      "aws": {
        "version": "~> 2.0",
        "source": "aws"
      }
    }
  },
  "provider": {
    "aws": [
      {
        "region": "us-east-1"
      }
    ]
  },
  "resource": {
    "aws_instance": {
      "hello": {
        "ami": "ami-2757f631",
        "instance_type": "t2.micro",
        "//": {
          "metadata": {
            "path": "hello-terraform/hello",
            "uniqueId": "hello",
            "stackTrace": [
              ... ## Output truncated
            ]
          }
        }
      }
    }
  },
  "output": {
    "hello_public_ip": {
      "value": "${aws_instance.hello.public_ip}"
    }
  }
}

»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 deploy command.
You can navigate into cdktf.out and deploy your application using the Terraform CLI workflow (terraform init, terraform plan, and terraform 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.hello

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.

Deploying Stack: hello-terraform
Resources
 ✔ AWS_INSTANCE         hello               aws_instance.hello

Summary: 1 created, 0 updated, 0 destroyed.

Output: hello_public_ip = 3.94.158.89

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 updated application. Remember to confirm your run with a yes.

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

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.

AWS Console

»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.hello

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: hello-terraform
Resources
 ✔ AWS_INSTANCE         hello               aws_instance.hello

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, refer to the documentation in the terraform-cdk repository:

Infrastructure

Security

Networking

Applications