Starting with CDK part 1: Preparations, and Bare-Bones

Symphonia
Mike Roberts
Sep 19, 2022

The AWS Cloud Development Kit (CDK) is a tool you can use to deploy applications and infrastructure to AWS. From one of my earlier articles:

CDK has become, in its short history, a very popular infrastructure-as-code tool. It’s not too surprising why - it allows engineers to use richer programming languages to define infrastructure, rather than having to use JSON or YAML. With richer languages comes better tooling, better abstractions, and more.

An empty CDK app

While CDK is very powerful, it requires a fair amount of “ceremony” to get up and running. This is especially true when using CDK with TypeScript, currently my favorite implementation language for CDK. To help avoid all this work becoming a gumption trap I’ve developed a number of public “quick start” templates to help CDK beginners get going more quickly.

In this article you’ll be able to take your first steps using CDK and TypeScript. Specifically I use my most basic quick start - “Bare-Bones” - to guide you through the following:

  • Prepare your local environment to use CDK
  • Prepare your AWS account for CDK
  • Deploy and examine the “Bare-Bones” app

Whether to use CDK or not is not a simple decision - see my earlier article on its pros and cons - but if you want to dive in I hope that this guide will get you up and running quickly.

Before we start…

I’m thinking about writing a lot more about CDK. If you’re interested in this area please sign up below. You’ll be doing me a favor since I’ll get an idea of how many people are keen to hear about CDK, and in return I’ll let you know about new articles and open source updates as soon as they’re available. Thanks.

    Prepare your local environment

    The terminal examples in this article assume you are using a bash / zsh shell, or equivalent, with the leading $ signifying the terminal prompt. If you are using Windows you will need to adjust these commands if using a different type of terminal.

    CDK is an application that you run locally from a terminal. Because of this there are few things you need to set up locally first.

    Download the template project

    On your local machine copy or clone, into a new directory, this template project from GitHub. E.g. run the following:

    $ git clone git@github.com:symphoniacloud/cdk-bare-bones.git

    Note: My preference is not to install CDK globally on my machine, and so the version of CDK that you will use in this tutorial is defined in the project itself.

    Setup Node

    CDK with TypeScript runs locally in Node, so you need to have Node available in your terminal.

    There are various ways of managing Node, but here is my current preferred method:

    1. Install NVM in my user-global environment
    2. Use NVM’s shell integration to automatically load the correct version of Node according to a .nvmrc file - the bare-bones template includes such a file.

    Node (with NPM) is the only language / runtime prerequisite for this template - e.g. CDK and TypeScript will be automatically installed locally to just the project directory based on the project’s own metadata file.

    AWS Profile

    If you don’t already have access to an AWS account you’ll need to signup here.

    CDK requires that your terminal be configured with an AWS profile that gives the credentials for a specific AWS account and region to deploy to. These credentials should provide suitably broad permissions - I recommend “Power User” or “Administrator” level permissions.

    To do this, perform the following tasks:

    1. If you haven’t already done so, install the AWS CLI
    2. If you haven’t already done so, configure the AWS CLI to use your permissions
    3. Run the following commands to make sure your profile is correctly configured:
    $ aws sts get-caller-identity --query 'Account' --output text
123456789012

$ aws configure get region
us-east-1

    In this example my profile is targeting AWS Account ID 123456789012 in the us-east-1 region. If the answers you get don’t match your account and region, then fix your profile configuration before continuing.

    Strictly speaking you don’t need to use the AWS CLI to use this template project, but it makes things a lot easier to have the AWS CLI setup.

    Prepare your AWS Account

    Check to see whether your account has been bootstrapped

    Your AWS account must be bootstrapped for CDK before you can deploy to it with CDK.

    If your account is using the default CDK bootstrap configuration then the bootstrap will be deployed to CloudFormation with the stack name CDKToolkit. You can examine your account to see if this is the case by running the following:

    $ aws cloudformation describe-stacks --stack-name CDKToolkit

    This will return the stack details, or an error if the stack doesn’t exist.

    If your account has already been bootstrapped for CDK then skip the rest of this Prepare your AWS Account section, otherwise read on.

    Bootstrap your AWS account (only if necessary!)

    IMPORTANT: - CDK Bootstrapping has security implications, and should not be performed on sensitive accounts without considering the ramifications. For more details about CDK Bootstrapping, see the AWS Documentation.

    From the documentation:

    Deploying AWS CDK apps into an AWS environment (a combination of an AWS account and region) requires that you provision resources the AWS CDK needs to perform the deployment. These resources include an Amazon S3 bucket for storing files and IAM roles that grant permissions needed to perform deployments. The process of provisioning these initial resources is called bootstrapping.

    CDK Bootstrapping can be highly customized, but to use the default settings you can run the following from the root of the project directory you downloaded earlier. NOTE - this will use the AWS account and region setup in your profile, see AWS Profile above.

    $ npm install && npx cdk bootstrap --output build/cdk.out

    This will take a couple of minutes, but the output should look something like this once complete:

     ✅  Environment aws://123456789012/us-east-1 bootstrapped.

    The Bare-Bones application

    Now that everything is set up actually deploying the application is very simple!

    $ npm install && npm run deploy

    If successful, the end result will look something like this:

    ✨  Deployment time: 18.19s

Stack ARN:
arn:aws:cloudformation:us-east-1:123456789012:stack/app-stack/12345678-1234-1234-1234-123456789ab

✨  Total time: 20.71s

    The deployed application is the smallest possible CDK app - the only deployed resource is some CDK Metadata.

    Once you’ve run npm install once in the project directory you won’t need to again

    What just happened?

    When you ran the above command CDK created a CloudFormation stack in your AWS account. CloudFormation is AWS’ service used to deploy resources to an AWS account and to keep track of the state of resource groups - stacks - so that when subsequent updates are required only the necessary resources are changed.

    CDK is, effectively, a wrapper around CloudFormation. When you deploy a CDK app what’s actually going on is that you are deploying one or more CloudFormation stacks.

    Because CDK is a local wrapper to actually see what CDK did in your AWS account you need to visit the CloudFormation section of the AWS web console at https://console.aws.amazon.com/cloudformation . If you go here you should be able to see a new stack named ‘app-stack’, and if you click on it, then click Resources it should look something like this:

    CDK app deployed to CloudFormation

    The Resources tab shows all the deployed resources within the CDK app. Right now that’s just metadata.

    The code in our infrastructure-as-code

    CDK is an infrastructure-as-code tool. So where’s the code? The top level of the code is at src/cdk/app.ts, and looks like the following:

    #!/usr/bin/env node
import 'source-map-support/register';
import {App, Stack, StackProps} from 'aws-cdk-lib';
import {Construct} from 'constructs';
import {createStackProps} from "./initSupport";

class AppStack extends Stack {
    constructor(scope: Construct, id: string, props: StackProps) {
        super(scope, id, props);
    }
}

const app = new App();
new AppStack(app, 'AppStack', createStackProps(app, 'app-stack'));

    There’s a fair bit going on here, but the most important part is the contents of the constructor function - this is where you’d put all of your actual resources. Right now it’s empty - for an example of what it looks like to have some actual resources see one of my other templates.

    Next steps

    Congratulations - you’ve prepared your environment for CDK and deployed your first CDK app!

    At this point you’ll probably want to add some resources to your app, similarly to the example I just linked to. You can see all the resources you can use in the CDK documentation, e.g. see here for how to add an S3 bucket. I’ll also be describing this more in a future article.

    You may also be interested in why I’ve set up the template in the way that I have. For that, and other extension ideas, see the README in the bare-bones project.

    I hope you’ve found this article useful! Again, if you’re interested in hearing more about CDK I’d appreciate it if you subscribe for updates, if you haven’t done so already. Alternatively if you have feedback, or are interested in help, then drop me a line at mike@symphonia.io.

      « Starting with CDK part 2: Deploying a Lambda Application Java and AWS Lambda - Best of frenemies? »