Getting Started with AWS CDK

Tags: aws cdk cloudformation typescript python

Cloudformation service in AWS allows you to describe an entire set of resources required to make a pipeline. The cloudformation template can be described in JSON or YAML format. Updating the cloudformation template was not a pleasant experience. I wanted to discover alternative ways to generate cloudformation template programmatically.

The CDK library provides you a way to declare the resources in your favorite languages like Java, Javascript, Typescript, and Python. In this tutorial, we will use typescript and python to generate our cloudformation template.

Before we begin

Just a quick referesher to few concepts before we delve into AWS CDK

1. Cloudformation template describes AWS resources. A running instance of cloudformation is called a stack.

2. Constructs are the basic building blocks of AWS CDK apps.

3. L1 construct are named CfnXyz, where Xyz is name of the resource. They are low-level construct which directly represent cloudformation resources.

4. L2 construct provide common boilerplates and glue logic. These will come with convenient defaults and reduces the amount of knowledge you need to know about them.

5. L3 construct are called high-level patterns. These constructs are designed to help you complete common tasks in AWS, often involving multiple kinds of resources.

For this tutorial, we will use L1 construct. However same concept can be used for L2 construct.

Installation

First, install the AWS CDK CLI from command line using

$ npm i -g aws-cdk@latest

Let’s create a project

• Typescript
• Python

	$ mkdir test-cdk
	$ cd test-cdk
	$ cdk init sample-app --language=typescript

view raw initial1.sh hosted with ❤ by GitHub

	$ mkdir test-cdk
	$ cd test-cdk
	$ cdk init sample-app --language=python
	# For cygwin on Windows
	$ source .venv/Script/activate
	# For Mac or Linux
	$ source .venv/bin/activate
	(.venv) $ python -m pip install -r requirements.txt

view raw initial2.sh hosted with ❤ by GitHub

Then you can verify

	$ cdk doctor
	- CDK Version: 2.3.0 (build beaa5b2)
	- AWS environment variables:
	- AWS_NODEJS_CONNECTION_REUSE_ENABLED = 1
	- AWS_SDK_LOAD_CONFIG = 1
	- AWS_STS_REGIONAL_ENDPOINTS = regional
	- No CDK environment variables

view raw cdk-doctor.sh hosted with ❤ by GitHub

For our first use case, will add Parameters to our cloudformation. We need to edit file lib\test-cdk-stack.ts for typescript or lib\test_cdk_stack.py for python.

• Typescript
• Python

	import { Aws, CfnMapping, CfnParameter, Duration, Stack, StackProps } from 'aws-cdk-lib';
	import { Construct } from 'constructs';
	export class TestCdkStack extends Stack {
	constructor(scope: Construct, id: string, props?: StackProps) {
	super(scope, id, props);
	// create parameters
	new CfnParameter(this,
	"Application", {
	type: "String",
	default: "Cdk Tutorial"
	})
	new CfnParameter(this,
	"Environment", {
	type: "String",
	default: "development",
	allowedValues: ["development", "production"]
	})
	}
	}

view raw test-cdk-stack.ts hosted with ❤ by GitHub

	from constructs import Construct
	from aws_cdk import (
	Duration,
	Stack,
	CfnParameter
	)
	class TestCdkStack(Stack):
	def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
	super().__init__(scope, construct_id, **kwargs)
	# create parameters
	CfnParameter(self,
	id="Application",
	default="CDK Tutorial",
	type="String")
	CfnParameter(self,
	id="Environment",
	default="development",
	allowed_values= ["development", "production"])

view raw test_cdk_stack.py hosted with ❤ by GitHub

We can see the output of the cloudformation template by using the following command

$ cdk synth

If you want to generate cloudformation template without metadata

$ cdk synth --version-reporting false --path-metadata false 

The output is

	Parameters:
	Application:
	Type: String
	Default: CDK Tutorial
	Environment:
	Type: String
	Default: development
	AllowedValues:
	- development
	- production
	BootstrapVersion:
	Type: AWS::SSM::Parameter::Value<String>
	Default: /cdk-bootstrap/hnb659fds/version
	Description: Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]
	Rules:
	CheckBootstrapVersion:
	Assertions:
	- Assert:
	Fn::Not:
	- Fn::Contains:
	- - "1"
	- "2"
	- "3"
	- "4"
	- "5"
	- Ref: BootstrapVersion
	AssertDescription: CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI.

view raw synth_output1.yaml hosted with ❤ by GitHub

For CDK v2, CheckBootstrapVersion rule is added to the Stack's template as a safety check, to verify that the bootstrap stack in the target environment meets the minimum requirements of the current stack¹.

Stepfunction

The cloudformation template needs at least one resource to validate. We will add a stepfunction to our cloudformation. We will define our stepfunction inside a json file, helloworld.asl.json

{
  "Comment" : "A very very simple StepFunction",
  "StartAt": "Hello", 
  "States": {
    "Hello": {
      "Type": "Wait",
      "Seconds": 10,
      "Next": "World"
    },
    "World": {
      "Type": "Pass",
      "End": true
    }
  }
}

If you are not familiar with Stepfunction, AWS Stepfunction console has a nice visualization

Next we need to upload the helloworld.asl.json to s3 bucket. We also need to define a mapping to access this json file.

• Typescript
• Python

	import { Aws, CfnMapping, CfnParameter, Duration, Stack, StackProps } from 'aws-cdk-lib';
	import { CfnMap } from 'aws-cdk-lib/aws-location';
	import { Construct } from 'constructs';
	export class TestCdkStack extends Stack {
	constructor(scope: Construct, id: string, props?: StackProps) {
	super(scope, id, props);
	// create parameters
	new CfnParameter(this,
	"Application", {
	type: "String",
	default: "Cdk Tutorial"
	})
	new CfnParameter(this,
	"Environment", {
	type: "String",
	default: "development",
	allowedValues: ["development", "production"]
	})
	// create mapping
	const myMap = new CfnMapping(this,
	"MyMapping", {
	lazy: true,
	mapping: {
	"development": {
	S3Bucket: "development-s3-bucket",
	S3Key: "development-s3-prefix"
	},
	"production": {
	S3Bucket: "development-s3-bucket",
	S3Key: "development-s3-prefix"
	}
	}
	})
	}
	}

view raw test-cdk-stack2.ts hosted with ❤ by GitHub

	from constructs import Construct
	from aws_cdk import (
	Duration,
	Stack,
	CfnParameter,
	CfnMapping
	)
	class TestCdkStack(Stack):
	def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
	super().__init__(scope, construct_id, **kwargs)
	# create parameters
	CfnParameter(self,
	id="Application",
	default="CDK Tutorial",
	type="String")
	CfnParameter(self,
	id="Environment",
	default="development",
	allowed_values= ["development", "production"])
	# create mapping
	my_map = CfnMapping(self,
	id="MyMapping",
	lazy=True,
	mapping= {
	"development": {
	"S3Bucket": "development-s3-bucket",
	"S3Key": "development-s3-prefix"
	},
	"production": {
	"S3Bucket": "production-s3-bucket",
	"S3Key": "production-s3-prefix"
	}
	})

view raw test_cdk_stack2.py hosted with ❤ by GitHub

Our output will still be the same since our mapping is lazy. Next, we will add stepfunction to our resources

• Typescript
• Python

	import { Aws, CfnMapping, CfnParameter, Duration, Fn, Stack, StackProps } from 'aws-cdk-lib';
	import { CfnMap } from 'aws-cdk-lib/aws-location';
	import { CfnStateMachine } from 'aws-cdk-lib/aws-stepfunctions';
	import { Construct } from 'constructs';
	export class TestCdkStack extends Stack {
	constructor(scope: Construct, id: string, props?: StackProps) {
	super(scope, id, props);
	// create parameters
	new CfnParameter(this,
	"Application", {
	type: "String",
	default: "Cdk Tutorial"
	})
	new CfnParameter(this,
	"Environment", {
	type: "String",
	default: "development",
	allowedValues: ["development", "production"]
	})
	const stepfunctionRole = new CfnParameter(this,
	"StepFunctionRole", {
	type: "String",
	default: "put-your-stepfunction-execution-role"
	})
	// create mapping
	const myMap = new CfnMapping(this,
	"MyMapping", {
	lazy: true,
	mapping: {
	"development": {
	S3Bucket: "development-s3-bucket",
	S3Key: "development-s3-prefix"
	},
	"production": {
	S3Bucket: "development-s3-bucket",
	S3Key: "development-s3-prefix"
	}
	}
	})
	// create stepfunction
	new CfnStateMachine(this,
	"DemoStepFunction", {
	definitionS3Location: {
	"bucket": myMap.findInMap("development", "S3Bucket"),
	"key": myMap.findInMap("development", "S3Key")
	},
	roleArn: "arn:aws:iam::" + Aws.ACCOUNT_ID + ":role/" + stepfunctionRole.valueAsString,
	stateMachineType: "STANDARD",
	tags: [{
	"key": "environment",
	"value": "development"
	}]
	})
	}
	}

view raw test-cdk-stack3.ts hosted with ❤ by GitHub

	from constructs import Construct
	from aws_cdk import (
	Duration,
	Stack,
	CfnParameter,
	CfnMapping,
	Aws,
	Fn,
	aws_stepfunctions as sfn
	)
	class TestCdkStack(Stack):
	def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
	super().__init__(scope, construct_id, **kwargs)
	# create parameters
	CfnParameter(self,
	id="Application",
	default="CDK Tutorial",
	type="String")
	CfnParameter(self,
	id="Environment",
	default="development",
	allowed_values= ["development", "production"])
	CfnParameter(self,
	id="StepFunctionRole",
	default="put-your-stepfunction",
	type="String")
	# create mapping
	my_map = CfnMapping(self,
	id="MyMapping",
	lazy=True,
	mapping= {
	"development": {
	"S3Bucket": "development-s3-bucket",
	"S3Key": "development-s3-prefix"
	},
	"production": {
	"S3Bucket": "production-s3-bucket",
	"S3Key": "production-s3-prefix"
	}
	})
	# add step function
	sfn.CfnStateMachine(self,
	id="DemoStepFunction",
	definition_s3_location = {
	"bucket": my_map.find_in_map("development", "S3Bucket"),
	"key": my_map.find_in_map("development", "S3Key")
	},
	role_arn="arn:aws:iam::" + Aws.ACCOUNT_ID + ":role/" + Fn.ref("StepFunctionRole"),
	state_machine_type="STANDARD",
	tags= [
	{
	"key": "environment",
	"value": "development"
	}
	])

view raw test_cdk_stack3.py hosted with ❤ by GitHub

The final cloudformation template is

	Parameters:
	Application:
	Type: String
	Default: CDK Tutorial
	Environment:
	Type: String
	Default: development
	AllowedValues:
	- development
	- production
	StepFunctionRole:
	Type: String
	Default: put-your-stepfunction-execution-role
	BootstrapVersion:
	Type: AWS::SSM::Parameter::Value<String>
	Default: /cdk-bootstrap/hnb659fds/version
	Description: Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]
	Resources:
	DemoStepFunction:
	Type: AWS::StepFunctions::StateMachine
	Properties:
	RoleArn:
	Fn::Join:
	- ""
	- - "arn:aws:iam::"
	- Ref: AWS::AccountId
	- :role/
	- Ref: StepFunctionRole
	DefinitionS3Location:
	Bucket: development-s3-bucket
	Key: development-s3-prefix
	StateMachineType: STANDARD
	Tags:
	- Key: environment
	Value: development
	Rules:
	CheckBootstrapVersion:
	Assertions:
	- Assert:
	Fn::Not:
	- Fn::Contains:
	- - "1"
	- "2"
	- "3"
	- "4"
	- "5"
	- Ref: BootstrapVersion
	AssertDescription: CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI.

view raw synth_output2.yaml hosted with ❤ by GitHub

The cloudformation template is generated under

# for typescript
cdk.out\TestCdkStack.template.json
# for python 
cdk.out\test_cdk.template.json

Or you can simply deploy it using

$ cdk deploy

Footnotes

---

1. Github issues

   ↩

---

comments powered by Disqus