DEV Community: Lee Priest

The Energy Drink Episodes 4: The Return Of The Lambda Functions

Lee Priest — Tue, 19 Dec 2023 11:32:27 +0000

This post is the fourth part of a ‘Let’s CDK’ series. You can catch up on part 1 here, part 2 here and part 3 here. This post is part of a series that will introduce you to the AWS Cloud Development Kit (CDK) and how it can be used to create an application. This series will introduce you to the core concepts of AWS CDK, how you can deploy to your AWS account, and how services like AWS Lambda Functions, DynamoDB, Step Functions and more can all be used when working with CDK.

Our Previous Steps

In the last episode, we learned about AWS Step Functions and how we can create them using CDK. We created our own custom L3 construct for an express workflow Step Function and then created the body definition chain. We linked it all together nicely in a stack and then integrated it with our main app stack. Feel free to have a read-through of the previous episode if you need any refresher before you continue on.

There’s nothing wrong with returning!

Now that we’ve refreshed our memories of the last episode, you may be aware that there were a couple of things that we added as placeholders that we promised to return to. These ‘things’ were the Lambda Functions that we use to perform some logic on our payload in our Express Step Function flow.

Let’s take a quick look at how we implemented these Lambda functions via CDK in the previous episode:

const sugarFreeLambdaFunction = new NodejsFunction(this, 'SugarFreeLambdaFunction', {
    entry: path.join(__dirname, '../src/functions/sugarFree/sugarFree.ts'),
    runtime: Runtime.NODEJS_18_X,
    architecture: Architecture.ARM_64,
    handler: 'sugarFree',
    bundling: {
        sourceMap: true,
        minify: true,
        tsconfig: path.join(__dirname, '../tsconfig.json'),
    },
});

We used the NodejsFunction construct to build a Node.js Lambda function bundled using esbuild. However, if we look a little closer at the implementation, there are some things that we will likely keep the same between all our Lambda functions we end up using. Things like the runtime, architecture and bundling probably won’t change. Could we come up with a way to implement something that would handle this for us?

Let’s Construct Something…

Terrible pun aside, you probably guessed that we can create a custom L3 construct for our Lambda functions. In this custom construct we can set sensible defaults that we want all of our Lambda functions to use. We can also make use of a props object so things like the entry, handler and tsconfig can be dynamic.

To get started with our custom Lambda function construct let’s create a LambdaFunctions directory in our constructs directory. Inside there, let’s now create a TSLambdaFunction.ts file to house our construct code. Your constructs directory structure should look a little something like this:

src/
│
└───constructs/
    │
    ├───APIGateway/
    │
    └───LambdaFunctions/
    │
    └───StepFunctions/

In our new TSLambdaFunctions.ts file, let’s take a look at what we’ll need to be importing:

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import { Architecture, Runtime } from "aws-cdk-lib/aws-lambda";

Hopefully, you can see some familiar faces in the imports above. The trusty Stack and Construct imports have been used throughout the series. The NodejsFunction import provides us with the construct we are going to use to create the actual Lambda function. You may be wondering why we don’t just use the Function construct to create our Lambda functions.

As we’re working on a Node.js application, the NodejsFunction construct makes things a lot simpler for us by handling the code bundling. As we’re also working in Typescript, the construct makes things easier for us again by handling the compilation from Typescript to Javascript. In a nutshell, as we’re working in Typescript, using the NodejsFunction construct saves us time and effort and helps us get up and running quicker.

The Architecture and Runtime imports allow us to specify, as you can probably guess, what architecture and runtime our Lambda function should use. Although these two imports aren’t completely necessary, as they are optional props for the NodejsFunction construct, we can specify our own values to override the defaults.

Next, let’s have a think about the props that we will want to be able to pass into our TSLambdaFunction construct:

type LambdaFunctionProps = {
    serviceName: string;
    stage: string;
    entryPath: string;
    handlerName?: string;
    tsConfigPath: string;
}

Breaking down the type above, we can see:

serviceName: A string we will use to create the logical ID for our Lambda function
stage: A string we will use to create the logical ID for our Lambda function. This could also be used to handle deployment stage-specific needs if needed.
entryPath: A string that represents the path to the Lambda function handler code
handlerName: An optional string that represents that name of the exported function from the entry file
tsConfigPath: A string that represents the path to the tsconfig file. We will pass this explicitly so the construct knows exactly where our tsconfig file is rather than it having to try to work it out itself.

Now we have our imports and our props decided. Let’s get cracking on actually creating the construct. We can make use of the skeleton we’re familiar with:

export class TSLambdaFunction extends Construct {
    public readonly tsLambdaFunction: NodejsFunction;

    constructor(scope: Stack, id: string, props: LambdaFunctionProps) {
        super(scope, id);

         // This is where the fun stuff will live!
    }
}

In the code above, we have the skeleton for our TSLambdaFunction that extends the Construct class. We set a public readonly property called tsLambdaFunction so we are able to access the Lambda function created inside this construct when used inside our stacks.

It’s time to have some fun by adding some meat to the bones of our skeleton. This ‘meat’ looks a little something like this:

const {
    serviceName,
    stage,
    entryPath,
    handlerName = 'handler',
    tsConfigPath
} = props;

this.tsLambdaFunction = new NodejsFunction(this, `${serviceName}-${id}-${stage}`, {
    entry: entryPath,
    runtime: Runtime.NODEJS_18_X,
    architecture: Architecture.ARM_64,
    handler: handlerName,
    bundling: {
        sourceMap: true,
        minify: true,
        tsconfig: tsConfigPath,
    },
});

In the above code, we first destructure parameters from our props object and then use the NodejsFunction construct to create a Lambda function. This Lambda function is then set as the value of the readonly property we created.

For our architecture, we went with Architecture.ARM_64 for the benefits like cost efficiency, performance and energy efficiency over the default of Architecture.X86_64 that the NodejsFunction runs with. We also went with Runtime.NODEJS_18_X as opposed to the default of Runtime.NODEJS_LATEST out of caution, as I’ve been burned by Node version issues in the past. But in reality, for our app, the default would have been fine.

With the snippets above, we have everything we need to be able to successfully create Lambda functions. The above can also be easily extended to include things like log groups, deployment options, alarms and much more. If we combine the above snippets we get this:

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import { Architecture, Runtime } from "aws-cdk-lib/aws-lambda";

type LambdaFunctionProps = {
    serviceName: string;
    stage: string;
    entryPath: string;
    handlerName?: string;
    tsConfigPath: string;
}

export class TSLambdaFunction extends Construct {
    public readonly tsLambdaFunction: NodejsFunction;

    constructor(scope: Stack, id: string, props: LambdaFunctionProps) {
        super(scope, id);

        const {
            serviceName,
            stage,
            entryPath,
            handlerName = 'handler',
            tsConfigPath
        } = props;

        this.tsLambdaFunction = new NodejsFunction(this, `${serviceName}-${id}-${stage}`, {
            entry: entryPath,
            runtime: Runtime.NODEJS_18_X,
            architecture: Architecture.ARM_64,
            handler: handlerName,
            bundling: {
                sourceMap: true,
                minify: true,
                tsconfig: tsConfigPath,
            },
        });
    }
}

Time to Handle Our Handlers

With our custom Lambda function construct now constructed, we can turn our attention to the placeholder handlers we created in the previous episode. As a refresher, this is what we currently have:

export const sugar = async () => {
    return {
        statusCode: 200,
        body: {
          message: "Hello, Sugar World!"
        },
    };
}

This extremely basic placeholder won't fulfil the mission we need it to:

Decide which energy drink we should drink

We will stick to a basic approach in how we’re going to figure out which drink we’ll be given so we don’t get too far away from the mission of this post:

To learn how to create and deploy a Lambda function using CDK

To contain everything to the Lambda handler, we can use a very basic implementation as follows:

type sugarEvent = {
  sugar: boolean
}

export const sugar = async (event: sugarEvent) => {
    const {sugar} = event;

    if(sugar) {
      return {
        drinkName: 'Relentless'
      }
    }

    throw new Error('Sugar boolean is false, should be true');
}

The above snippet shows the Lambda function handler receives an event that contains a sugar parameter that is a boolean. There is then a simple check in the code to detect if the sugar boolean is true or not. If it is true we return the drinkName of Relentless. Otherwise, we throw an error. If you think back to our Step Function, we will have two separate handlers for the sugar and the sugar-free path. This means that if our sugar Lambda Function receives a boolean that is false, something has gone wrong somewhere. For our sugarFree Lambda Function we can use the same structure:

type sugarEvent = {
  sugar: boolean
}

export const sugarFree = async (event: sugarEvent) => {
    const {sugar} = event;

    if(!sugar) {
      return {
        drinkName: 'Relentless Sugar Free'
      }
    }

    throw new Error('Sugar boolean is true, should be false');
}

Step Back to Our Definition

Custom Lambda function construct, check. Updated Lambda handlers, check. We’re making good progress so far, so next up is updating our Step Function definition. Don’t be scared! There isn’t much we actually need to update. Let’s first have a refresher on what our current definition looks like:

const definition = storeRawItem.addCatch(failState).next(
    validatePayload
        .when(Condition.isPresent('$.sugar'), isSugarFree
            .when(Condition.booleanEquals('$.sugar', true), new LambdaInvoke(stack, 'Sugar Logic', {
                lambdaFunction: sugarLambdaFunction,
            }).addCatch(sugarPassState, { errors: ['States.ALL'] }))
            .otherwise(new LambdaInvoke(stack, 'Sugar Free Logic', {
                lambdaFunction: sugarFreeLambdaFunction,
            }).addCatch(sugarFreePassState, { errors: ['States.ALL'] }))
        )
        .otherwise(failState)
);

Looking at the above definition, we can see that the Lambda functions are being invoked depending on the presence of and the value of the sugar parameter in the Step Function input. To work out what updates we need to make to the Step Function definition, let’s consider the updates made to our Lambda Function handlers.

The handlers now return an object with a drinkName parameter. This parameter contains the value of the drink we have been assigned. With this in mind, we should get that drinkName parameter from the Lambda Function so we can return it to the user that triggered the Step Function. We can do this by updating the definition like this:

const definition = storeRawItem.addCatch(failState).next(
    validatePayload
        .when(Condition.isPresent('$.sugar'), isSugarFree
            .when(Condition.booleanEquals('$.sugar', true), new LambdaInvoke(stack, 'Sugar Logic', {
                lambdaFunction: sugarLambdaFunction,
                resultSelector: {
                    drinkName: JsonPath.stringAt('$.Payload.drinkName')
                }
            }).addCatch(sugarPassState, { errors: ['States.ALL'] }))
            .otherwise(new LambdaInvoke(stack, 'Sugar Free Logic', {
                lambdaFunction: sugarFreeLambdaFunction,
                resultSelector: {
                    drinkName: JsonPath.stringAt('$.Payload.drinkName')
                }
            }).addCatch(sugarFreePassState, { errors: ['States.ALL'] }))
        )
        .otherwise(failState)
);

On the whole, the definition hasn’t changed much at all. The use of resultSelector enables us to get the result from the Lambda Function and then set it as the Step Function data. So when we run the Step Function now, the result would be formatted like this:

{
  "drinkName": "Relentless Sugar Free"
}

For our needs, that’s all we need to update when considering the Step Function definition. Not so scary after all, right?

Stack Up Those Updates

Our Lambda Function construct is ready to go, the handler code has been updated and the Step Function definition is all good, so what next? Let’s take a look at our EnergyDrinkSelectorStepFunctionStack and see what updates we may need there.

The stack should currently look like this:

import path = require("path");
import { Construct } from "constructs";
import { NestedStack, NestedStackProps } from "aws-cdk-lib";
import { StateMachine } from "aws-cdk-lib/aws-stepfunctions";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import { Architecture, Runtime } from "aws-cdk-lib/aws-lambda";
import { ITable } from "aws-cdk-lib/aws-dynamodb";
import { ExpressStepFunction } from "../constructs/StepFunctions/ExpressStepFunction";
import { energyDrinkSelectorDefinition } from "../src/stepFunctions/definitions/energyDrinkSelector";

type EnergyDrinkSelectorStepFunctionStackProps = NestedStackProps & {
    table: ITable;
}

export class EnergyDrinkSelectorStepFunctionStack extends NestedStack {
    public readonly stepFunction: StateMachine;

    constructor(scope: Construct, id: string, props: EnergyDrinkSelectorStepFunctionStackProps) {
        super(scope, id, props);

        const { table } = props;

        const sugarFreeLambdaFunction = new NodejsFunction(this, 'SugarFreeLambdaFunction', {
            entry: path.join(__dirname, '../src/functions/sugarFree/sugarFree.ts'),
            runtime: Runtime.NODEJS_18_X,
            architecture: Architecture.ARM_64,
            handler: 'sugarFree',
            bundling: {
                sourceMap: true,
                minify: true,
                tsconfig: path.join(__dirname, '../tsconfig.json'),
            },
        });

        const sugarLambdaFunction = new NodejsFunction(this, 'SugarLambdaFunction', {
            entry: path.join(__dirname, '../src/functions/sugar/sugar.ts'),
            runtime: Runtime.NODEJS_18_X,
            architecture: Architecture.ARM_64,
            handler: 'sugar',
            bundling: {
                sourceMap: true,
                minify: true,
                tsconfig: path.join(__dirname, '../tsconfig.json'),
            },
        });

        const energyDrinkSelectorStepFunction = new ExpressStepFunction(this, 'EnergyDrinkSelectorExpress', {
            serviceName: 'energy-drink-selector',
            stage: 'dev',
            definition: energyDrinkSelectorDefinition({
                stack: this,
                energyDrinkTable: table,
                sugarLambdaFunction: sugarLambdaFunction, 
                sugarFreeLambdaFunction: sugarFreeLambdaFunction
            }),
        });

        this.stepFunction = energyDrinkSelectorStepFunction.stateMachine;
    }
};

Hopefully, you can see a few places where we can make some updates to make use of our new TSLambdaFunction construct and maybe a little housekeeping, too.

The first thing we can do is take the tsconfig path we’re creating and store that in a variable before we create our Lambda functions. Let’s add that underneath the destructuring of the table parameter from the props object:

const tsConfigPath = path.join(__dirname, '../tsconfig.json');

Next, we can update how we’re creating the Lambda functions in the stack. We can use our shiny new L3 construct but we’ll first need to import it, let’s add the import at the top of the file with the rest of the imports and remove the NodejsFunction import:

import path = require("path");
import { Construct } from "constructs";
import { NestedStack, NestedStackProps } from "aws-cdk-lib";
import { StateMachine } from "aws-cdk-lib/aws-stepfunctions";
import { ITable } from "aws-cdk-lib/aws-dynamodb";
import { ExpressStepFunction } from "../constructs/StepFunctions/ExpressStepFunction";
import { energyDrinkSelectorDefinition } from "../src/stepFunctions/definitions/energyDrinkSelector";
import { TSLambdaFunction } from "../constructs/LambdaFunction/TSLambdaFunction";

With our imports updated, we can now use the TSLambdaFunction construct in place of the NodejsFunction construct. We can go from this:

const sugarFreeLambdaFunction = new NodejsFunction(this, 'SugarFreeLambdaFunction', {
    entry: path.join(__dirname, '../src/functions/sugarFree/sugarFree.ts'),
    runtime: Runtime.NODEJS_18_X,
    architecture: Architecture.ARM_64,
    handler: 'sugarFree',
    bundling: {
        sourceMap: true,
        minify: true,
        tsconfig: path.join(__dirname, '../tsconfig.json'),
    },
});

const sugarLambdaFunction = new NodejsFunction(this, 'SugarLambdaFunction', {
    entry: path.join(__dirname, '../src/functions/sugar/sugar.ts'),
    runtime: Runtime.NODEJS_18_X,
    architecture: Architecture.ARM_64,
    handler: 'sugar',
    bundling: {
        sourceMap: true,
        minify: true,
        tsconfig: path.join(__dirname, '../tsconfig.json'),
    },
});

To this:

const sugarFreeLambdaFunction = new TSLambdaFunction(this, 'SugarFreeLambdaFunction', {
    serviceName: 'energy-drink-selector',
    stage: 'dev',
    handlerName: 'sugarFree',
    entryPath: path.join(__dirname, '../src/functions/sugarFree/sugarFree.ts'),
    tsConfigPath
});

const sugarLambdaFunction =  new TSLambdaFunction(this, 'SugarLambdaFunction', {
    serviceName: 'energy-drink-selector',
    stage: 'dev',
    handlerName: 'sugar',
    entryPath: path.join(__dirname, '../src/functions/sugar/sugar.ts'),
    tsConfigPath
});

Looks a bit neater and nicer, right? It remains somewhat familiar to the implementation of the NodejsFunction construct but becomes a little easier to read and has our defaults for bundling and other parameters handled. With these updates our EnergyDrinkSelectorStepFunctionStack should look like this:

import path = require("path");
import { Construct } from "constructs";
import { NestedStack, NestedStackProps } from "aws-cdk-lib";
import { StateMachine } from "aws-cdk-lib/aws-stepfunctions";
import { ITable } from "aws-cdk-lib/aws-dynamodb";
import { ExpressStepFunction } from "../constructs/StepFunctions/ExpressStepFunction";
import { energyDrinkSelectorDefinition } from "../src/stepFunctions/definitions/energyDrinkSelector";
import { TSLambdaFunction } from "../constructs/LambdaFunction/TSLambdaFunction";

type EnergyDrinkSelectorStepFunctionStackProps = NestedStackProps & {
    table: ITable;
}

export class EnergyDrinkSelectorStepFunctionStack extends NestedStack {
    public readonly stepFunction: StateMachine;

    constructor(scope: Construct, id: string, props: EnergyDrinkSelectorStepFunctionStackProps) {
        super(scope, id, props);

        const { table } = props;
        const tsConfigPath = path.join(__dirname, '../tsconfig.json');

        const sugarFreeLambdaFunction = new TSLambdaFunction(this, 'SugarFreeLambdaFunction', {
            serviceName: 'energy-drink-selector',
            stage: 'dev',
            handlerName: 'sugarFree',
            entryPath: path.join(__dirname, '../src/functions/sugarFree/sugarFree.ts'),
            tsConfigPath
        });

        const sugarLambdaFunction =  new TSLambdaFunction(this, 'SugarLambdaFunction', {
            serviceName: 'energy-drink-selector',
            stage: 'dev',
            handlerName: 'sugar',
            entryPath: path.join(__dirname, '../src/functions/sugar/sugar.ts'),
            tsConfigPath
        });

        const energyDrinkSelectorStepFunction = new ExpressStepFunction(this, 'EnergyDrinkSelectorExpress', {
            serviceName: 'energy-drink-selector',
            stage: 'dev',
            definition: energyDrinkSelectorDefinition({
                stack: this,
                energyDrinkTable: table,
                sugarLambdaFunction: sugarLambdaFunction.tsLambdaFunction, 
                sugarFreeLambdaFunction: sugarFreeLambdaFunction.tsLambdaFunction
            }),
        });

        this.stepFunction = energyDrinkSelectorStepFunction.stateMachine;
    }
};

Go Forth and Deploy!

With those last updates, we now have everything in place to have the full working end-to-end flow! We should now have a fully working app that can fulfil the mission of suggesting what energy drink we should drink based on a sugar/sugar-free preference.

Aaaaand relax

With this episode, we have covered quite a few things, with our main focus on how we can create Lambda functions in CDK.

We created our own custom L3 construct that contains sensible defaults we want all our Lambda functions to use. Having this custom construct will also help with any updates we may make going forward. We would only have to update this construct rather than track down every use of the NodejsFunction construct we were using in our initial implementation.

We also looked at our Step Function definition and how it needed to be updated to work with our updated Lambda handler code. We used resultSelector to extract the data we needed from the Lambda function and used it in our Step Function data.

Updates to the EnergyDrinkSelectorStepFunctionStack showed us how we could make use of our shiny new custom L3 construct in our stacks and replace the calls to the NodejsFunction construct.

Thank You! Yes, You!

This episode is the last in the series, as we now have a fully working app. Hopefully, you have been able to learn something during the process, even if it’s something small; I’ll take that as a win.

This series was never meant to be the ‘Let’s CDK’ series to end all ‘Let’s CDK’ series. The aim was to introduce you to AWS CDK and guide you through how to provision, create and deploy AWS resources and create a little app in the process. There is plenty of scope to build upon what we have built so far. It would be really cool to see anything you may want to add. Feel free to fork the Github repo and let me know about anything you create/update!

Thank you for taking the time to read this series of posts and for putting up with my terrible puns!

TL;DR

If you want to look at the code and don’t want to read my ramblings, navigate to this Github repo and spy on everything we’ll be creating in the series.

The Energy Drink Episodes 3: The Step Function Awakens

Lee Priest — Tue, 05 Dec 2023 17:32:14 +0000

This post is the third part of a ‘Let’s CDK’ series. You can catch up on part 1 here and part 2 here. This post is part of a series that will introduce you to the AWS Cloud Development Kit (CDK) and how it can be used to create an application. This series will introduce you to the core concepts of AWS CDK, how you can deploy to your AWS account, and how services like AWS Lambda Functions, DynamoDB, Step Functions and more can all be used when working with CDK.

Where were we?

In our last episode, we created a logical flow diagram for our app so we are sure of the purpose of the app and the flow we’ll need to achieve it. We also learned about the AWS CDK constructs for API Gateway and created our own custom L3 construct. We then created a stack and initialised our new custom construct to create our REST API. Feel free to have a read-through of the previous episode if you need any refresher before you continue on.

What are we doing today, Lee?

I’m glad you asked! If we look at the current state of our app, we can see that we’ve got a Stack, a Nested Stack and a REST API. It’s cool that we have those, but if we were to try and call the API, nothing would be invoked, and nothing would really happen. Let’s look at changing that.

Let’s take another look at our logical flow diagram:

At the moment, we are technically able to receive a request, but we don’t have any way of running logic against the incoming payload. Before diving in and throwing typescript around to create some handlers, let’s first think about what logic we want to run. Remember, this app we are building is an ‘Energy drink selector’, so we want to ensure we include relevant logic gates. Potential logic includes:

Payload validation: We want to be sure that the payload we receive is valid before we try to do too much with it.
Sugar vs. Sugar-free: The user wants to be able to have a drink recommendation based on their preference for sugar or sugar-free.

What Could We Use?

So, we have our logic needs decided. What AWS services could we use to enable us to run our logic checks? We could pass the payload straight from API Gateway to a Lambda function and then run our logic within that function. This would definitely work, but there are a couple of things that we may want to consider about this approach:

Having the payload validation in a Lambda function is not an issue. However, considering that we may have different validation needs dependent on the payload we receive could impact the size of the Lambda function and cause unnecessary bloat. We could also look at shifting the validation to a point before the lambda function is invoked and have an early return. This would save on unnecessary compute and would also be nicer on our wallets.
The logic for sugar vs. sugar-free would need to be contained within this single Lambda function. Sure, we could add this all in and get it to work, but we need to consider the long-term maintainability of the Lambda function. We should aim to keep our Lambda functions and all of our infrastructure as concise as possible.

Considering the above points, an alternative to a Lambda function could be using AWS Step Functions.

AWS Step Functions

If you have ever spoken to me, read anything I've written or listened to any talks I’ve done in relation to Serverless or infrastructure as code, there is a high likelihood that I have confessed my love for Step Functions. Even when unprompted. Putting my biases aside, however, there are some legitimate reasons we can consider using them in our app. If you are new to Step Functions or just fancy a refresher, have a read about them here.

AWS Step Functions provides serverless orchestration for modern applications. Orchestration centrally manages a workflow by breaking it into multiple steps, adding flow logic, and tracking the inputs and outputs between the steps.

In a nutshell, AWS Step Functions lets us create a workflow that we can configure to run various things. It allows us to run checks using flow steps, run actions using baked-in integrations with services like Dynamo DB and 200+ more AWS services, and use pre-built patterns to process S3 objects.

We could leverage many features baked into Step Functions to tackle the considerations we had above regarding using a single Lambda function.

Payload validation: A ‘Choice’ step would allow us to perform basic validation on the incoming payload. Things like checking that values exist and are of the correct type is something that’s easily possible. We can route to an error handler and exit early for any failed validation.
Specific routing: Another use of a ‘Choice’ step would be to route the execution based on part of the Step Function input. For example, if the incoming payload had sugar: false set, we could route down a specific path and eliminate running unnecessary compute and other steps.
We can still use Lambda Functions: For any logic that is a bit more in-depth, we can invoke a lambda function and pass in the payload via the Step Function. Combined with the “specific routing” mentioned above, we can create very concise Lamba functions with dedicated logic for that particular route.
Storage first pattern: We could also easily employ a storage first pattern using the built-in Dynamo DB integration. Jeremy Daly has a great article detailing the storage first pattern. Using this pattern will allow us to capture the raw input to the step function and potentially handle things like retries and a number of other things if needed.

With everything I’ve mentioned above and the article's title, you have probably worked out that we will use a Step Function rather than a single Lambda function to handle the ‘Run logic against request payload’ part of our logical flow.

Something to Consider

Step Functions come in two different ‘flavours’, or for the official term, workflow types. These two different types are standard and express.

Standard: This type of Step Function workflow is ideal for long-running workflows and can run for up to one year. They are billed by state transition and can use things like task tokens to enable the ‘pausing’ of an execution while another task is completed and a response is received.
Express: This type of Step Function workflow is ideal for high-volume, event-processing workflows and can run for up to five minutes. Express Step Functions are billed by the number of executions, duration of execution and the memory consumed while the execution ran. Express Step Function workflows can return synchronous responses when configured with StartSyncExecution.

Let’s now consider which type of workflow suits our needs the best. The payload we expect will be small and won't need much processing done to it. We won’t have any other microservices or third-party integrations to contact, so we won’t need a task token. We need to ensure that we can send a synchronous response back to the client that called so we can return their drink recommendation. Given the descriptions above, it looks like an Express workflow is the way to go!

Wait a Minute…

Before we create our Express Step Function, we need to make sure that we have the resources it will need to run, or at least some placeholders that we can flesh out later. As we are going to run a storage-first pattern, we will need to set up a Dynamo DB table. We will also need a couple of Lambda Functions to be able to run some logic against the incoming payload.

Let’s jump back into our code and open up energy-drink-selector-stack.ts in the lib directory. We currently have our API Gateway stack and a GET method setup that’s not really doing much. We can remove that GET method, as we’ll be hooking up our step function later.

Adding Our Dynamo DB Table

If you aren’t too familiar with Dynamo DB, I would definitely suggest having a read over the documentation. We aren’t going to be getting too in-depth with Dynamo DB, but we will be creating a table and running a PutItem call to store our incoming payload.

In order to create a new Dynamo DB table using CDK, we can refer to the documentation and see that there is a Table construct that we can use. Let’s use that Table construct to create our table:

const energyDrinkTable = new Table(this, 'EnergyDrinkDynamoTable', {
  tableName: 'EnergyDrinkTable',
  billingMode: BillingMode.PAY_PER_REQUEST,
  partitionKey: {
      name: 'PK',
      type: AttributeType.STRING
  },
  sortKey: {
      name: 'SK',
      type: AttributeType.STRING
  }
});

In the code snippet above, there are a few things we can see:

We initialise the Table construct and pass it the this value as its scope. Remember, this refers to our EnergyDrinkSelectorStack
For the second argument, we pass a logical ID
We set the tableName property to ‘EnergyDrinkTable’ to avoid using an autogenerated name provided by CDK. Just make sure that this value is always unique to avoid deployment headaches and other issues.
We then specify both a partition key and a sort key as PK and SK

So now our EnergyDrinkSelectorStack should look something like this:

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { APIGatewayStack } from '../stacks/APIGatewayStack';
import { AttributeType, Table, BillingMode } from 'aws-cdk-lib/aws-dynamodb';

export class EnergyDrinkSelectorStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const apiGatewayStack = new APIGatewayStack(this, 'EnergyDrinkSelectorAPIGatewayStack');

    const energyDrinkTable = new Table(this, 'EnergyDrinkDynamoTable', {
      tableName: 'EnergyDrinkTable',
      billingMode: BillingMode.PAY_PER_REQUEST,
      partitionKey: {
          name: 'PK',
          type: AttributeType.STRING
      },
      sortKey: {
          name: 'SK',
          type: AttributeType.STRING
      }
    });

  }
}

And with that, we now have our Dynamo DB table configured! When we next deploy, CDK will synthesise a CloudFormation template and create the Dynamo DB table for us.

Let’s Add Some Placeholders For Now…

So we have our shiny new Dynamo DB table configured. Let’s now turn our attention to the Lambda Functions. For the time being, we can set up some placeholder functions that won't do much but will allow us to configure our Step Function. We can always come back to the Lambda Functions later and flesh them out with whatever logic we need.

At the root of our project, let's add a src directory and, within that, a functions directory. This is where all of our Lambda Functions will live. Let’s also create a directory per Lambda Function. So, in our case, let’s create a sugar and sugarFree directory inside our functions directory. So our structure should look something like this:

src/
│
└───functions/
    │
    ├───sugar/
    │
    └───sugarFree/

As we can’t do too much with empty directories, let’s add a file to each one. Add a sugar.ts and a sugarFree.ts file in their respective directories. For the actual code in the .ts files, we are just going to have a very basic placeholder that will return a message. We can use the following code for our handler. Just make sure to update the name (sugar to sugarFree) and the message to match the file they are in:

export const sugar = async () => {
    return {
        statusCode: 200,
        body: {
          message: "Hello, Sugar World!"
        },
    };
}

Okay, we now have our Dynamo DB table and placeholder handler functions. We have everything we need to start building our Step Function!

Let’s Get Stepping!

There are a few different ways that you can build out Step Functions using CDK. One way we could approach it is by taking the JSON generated by the Workflow Studio and passing it as the definitionBody to the StateMachine construct. There is nothing wrong with this approach, and you can even set up some cool integrations in VS Code to visualise your step function.

The way we are going to approach our Step Function creation is to build out our definition ourselves using the various classes and constructs made available to use via the aws-cdk-lib library. Our first step on this journey is to create our own L3 construct so we can create our own express step function.

Create the Construct

Remember our constructs directory from the previous episode? Let’s head back there and create a new directory called StepFunctions. Inside that directory, create a new file called ExpressStepFunction.ts. Within our newly created file, let’s first add the imports we’ll be needing. These are:

import { Stack, Duration } from 'aws-cdk-lib';
import { LogGroup } from 'aws-cdk-lib/aws-logs';
import { Construct } from 'constructs';
import { 
  StateMachine, 
  DefinitionBody, 
  IChainable, 
  StateMachineType, 
  LogLevel 
} from 'aws-cdk-lib/aws-stepfunctions';

A quick look at the imports above shows that we are importing the Stack construct and the Duration class. The Stack will be used when assigning the type of the scope for our custom construct. Duration will be used to set the timeout duration. Importing LogGroup will allow us to create a new log group so we have some observability on our step function. As we’re creating our own custom construct, we need to extend the base Construct provided by the constructs library. Our final line of imports sees us importing all the fun things needed to initialise the StateMachine and ensure it has the correct typings and parameters set.

We can re-use the bare bones template we used when creating our APIGateway construct:

export class ExpressStepFunction extends Construct {
    constructor(scope: Stack, id: string, props: ExpressStepFunctionProps) {
        super(scope, id);

        // This is where we're gonna have some fun!        

    }
}

Before we start having the proper fun of fleshing out the construct, we need to define the ExpressStepFunctionProps type. Above the export, let’s add the following type:

type ExpressStepFunctionProps = {
    serviceName: string;
    stage: string;
    definition: IChainable;
    timeout?: number;
}

We have seen the serviceName and stage props before in our ApiGateway construct. But we now have two new parameters:

definition: Typed as IChainable. This will be the actual definition of the steps the step function should take. As the name suggests, the definition will consist of a bunch of chainable states.
timeout: Typed as a number. This number will be passed to the Duration we imported earlier, allowing us to specify a default or a specific timeout value for a given step function.

Now, we can have some fun fleshing out the construct. Let’s first destructure some variables from our props object and set up a new LogGroup for the Step Function. We can do this as follows:

const {
    serviceName,
    stage,
    definition,
    timeout = 5
} = props;

const logGroup = new LogGroup(
  this, 
  `${serviceName}-express-stepfn-logs-${stage}`
);

Using the LogGroup class, we created a new Cloudwatch log group that we can pass to the Step Function. I find it pretty cool that creating a log group is so easy, and hopefully, you do too! All we need to do is pass the scope, which is our Step Function construct, and the name of the log group, and CDK will work its magic at synth time.

note: If you get an error when trying to deploy relating to the LogGroup name, you may need to prefix the log group name. You can read more here.

Creating the actual state machine is also fairly straightforward. We can use the StateMachine construct and a few arguments, and we’re good to go:

this.stateMachine = new StateMachine(
  this, 
  `${serviceName}-express-stepfn-${stage}`, 
  {
     definitionBody: DefinitionBody.fromChainable(definition),
     timeout: Duration.minutes(timeout),
     stateMachineType: StateMachineType.EXPRESS,
     stateMachineName: `${serviceName}-express-stepfn-${stage}`,
     logs: {
      destination: logGroup,
      level: LogLevel.ALL,
      includeExecutionData: true
     }
  }
);

Let’s break down the StateMachine call above and the arguments passed to it:

this: The scope of the StateMachine, which, in this case, is our new Construct
${serviceName}-express-stepfn-${stage}: This is the string we’re passing as the logical ID. We use template strings to allow us to use variables to build the name dynamically. This could be expanded to take another variable like stepFunctionName or something similar to allow for more granularity. But for our current needs, it’s fine as is.
definitionBody: The ‘meat’ of our Step Function. This will be a chain of steps we pass that will be used to build out the steps in the Step Function.
timeout: The maximum Duration of time the Step Function can run for. We default this to 5, the default for an Express workflow.
stateMachineType: This is where we explicitly specify the Step Function type to be express. We do this using the StateMachineType.EXPRESS enum.
stateMachineName: Not to be confused with the logical ID. This is the name of the step function. So, if we’re looking in the AWS console, we can easily find it, as it won't be an auto-generated name given by CDK.
logs: This object allows us to specify our logging configuration for the Step Function. We pass the log group we created earlier as the destination for the logs. We also specify the level to be the enum LogLevel.ALL meaning that everything will get logged, not just errors or nothing at all. Setting includeExecutionData to true allows us to see the execution data in our logs.

An important thing to note when setting the logs object in your real-world applications:

Please be careful and don’t include any sensitive or PII data in your logs!

Let’s Get Defining!

We have our shiny new L3 Step Function construct, and now we need some actual step definitions to put it to good use. Let’s create a new directory in our src directory called stepFunctions. In the future, we may have some other fun things related to Step Functions in the directory, so let’s create a directory called definitions in this stepFunctions directory. With our directories created, let’s create a file called energyDrinkSelector.ts.

As we’ve done before, let’s start by looking at the imports we’ll need to create our definition:

import { 
  Pass, 
  Choice, 
  Fail, 
  JsonPath, 
  Condition 
} from "aws-cdk-lib/aws-stepfunctions";
import { 
  LambdaInvoke, 
  DynamoPutItem, 
  DynamoAttributeValue 
} from "aws-cdk-lib/aws-stepfunctions-tasks";
import { Stack } from 'aws-cdk-lib';
import { ITable } from 'aws-cdk-lib/aws-dynamodb';
import { IFunction } from "aws-cdk-lib/aws-lambda";

I won’t go through all of them, but you can see that we are importing various things from aws-cdk-lib/aws-stepfunctions and aws-cdk-lib/aws-stepfunctions-tasks. These refer to the flow steps (Pass, Choice, Fail, Condition) and integration tasks (LambdaInvoke, DynamoPutItem) we can use within Step Functions.

As we are still within the realm of Typescript, we need to define our type for the props the definition creation function we will create will receive:

type energyDrinkSelectorDefinitionProps = {
    stack: Stack
    energyDrinkTable: ITable,
    sugarFreeLambdaFunction: IFunction,
    sugarLambdaFunction: IFunction
}

We have the usual stack prop so that we can scope things correctly. We also are going to be passing the Dynamo DB table and Lambda Functions we created earlier.

The Definition Creator Function

Next, we can set up a function to create and return our definition. Let’s start by defining the function and the props it will receive based on the type we just defined:

export const energyDrinkSelectorDefinition = ({
    stack,
    energyDrinkTable,
    sugarFreeLambdaFunction,
    sugarLambdaFunction
}: energyDrinkSelectorDefinitionProps) => {

  // Looking mighty empty in here...

};

The above won’t get us too far, so let’s start adding things. The first thing we can do is create a call to Dynamo DB to store the ‘raw’ input received by the Step Function:

const storeRawItem = new DynamoPutItem(
  stack, 
  'StoreRawItem', 
  {
    item: {
        PK: DynamoAttributeValue.fromString(JsonPath.uuid()),
        SK: DynamoAttributeValue.fromString('RAWITEM'),
        body: DynamoAttributeValue.fromString(JsonPath.jsonToString(JsonPath.objectAt('$'))),
    },
    table: energyDrinkTable,
    resultPath: '$.dynamoResult'
  }
);

The above may look a little odd, especially in the item object, but we can break it down to remove the fear. Initialising the DynamoPutItem class, we pass the stack to ensure correct scoping, a logical ID and a props object. Within the props object, we can specify the fields of the item we want to create. As this call will be storing the ‘raw’ input, we are creating a ‘body’ parameter on the item object that will store the entire input passed to the step function execution.

All that scary-looking code on the body line, looking at youJsonPath, is how we can access the state of the execution and format it to a type that Dynamo DB is happy with. We use the objectAt method to find the object at the location $. In step function land, the $ represents the root of the execution state. So, accessing the object at this location will allow us to get the entire execution state. The jsonToString method is also used to make sure everything plays nicely with the DynamoAttributeValue and the item object matches what the DynamoPutItem method expects.

We pass the energyDrinkTable reference to the table parameter on the props object. This will ensure that when the execution runs, it stores the item in the correct Dynamo DB table. We will also use resultPath with our storage call and set that to store the result of the DynamoPutItem call in an object on the execution state called dynamoResult. This dynamoResult object could then be accessed at any point in the execution as it is made part of the execution state.

Creating the Definition Chain

Now that we have our storage action setup, we can start looking at creating the actual step function definition chain. The definition chain is where we will define things like our Choice, Pass and Fail states. We will also set our catch blocks for catching errors and specify when our Lambda Functions should be invoked. We can create our definition chain by doing the following:

const validatePayload = new Choice(stack, 'Validate Payload');
const isSugarFree = new Choice(stack, 'Sugar vs Sugar Free');
const sugarFreePassState = new Pass(stack, 'Sugar Free Error', {});
const sugarPassState = new Pass(stack, 'Sugar Error', {});
const failState = new Fail(stack, 'Fail', {});

const definition = storeRawItem.addCatch(failState).next(
    validatePayload
        .when(Condition.isPresent('$.sugar'), isSugarFree
            .when(Condition.booleanEquals('$.sugar', true), new LambdaInvoke(stack, 'Sugar Logic', {
                lambdaFunction: sugarLambdaFunction,
            }).addCatch(sugarPassState, { errors: ['States.ALL'] }))
            .otherwise(new LambdaInvoke(stack, 'Sugar Free Logic', {
                lambdaFunction: sugarFreeLambdaFunction,
            }).addCatch(sugarFreePassState, { errors: ['States.ALL'] }))
        )
        .otherwise(failState)
);

return definition;

We can see in the example above that we create the states that we will be needing for the execution and pass them the stack as their scope. We also pass in the name of the state.

After creating the states we need, we create the Step Function definition. The storeRawItem is called first to ensure we follow our storage first pattern, and then a .next allows us to chain on the next step in the Step Function. The validatePayload Choice state is run and checks for the existence of a sugar variable being present in the execution state. If the sugar variable is found, the chain continues on to the isSugarFree check. The .otherWise is used when conditions aren’t met. So, in this case, there is a .otherWise to go to the failState if the sugar variable is not present, and another to go to the LambdaInvoke of the sugar-free logic function if the sugar variable is found not to be set to true.

If all has gone to plan, you should end up with a definition create function file that looks something like this:

import { Pass, Choice, Fail, JsonPath, Condition } from "aws-cdk-lib/aws-stepfunctions";
import { LambdaInvoke, DynamoPutItem, DynamoAttributeValue } from "aws-cdk-lib/aws-stepfunctions-tasks";
import { Stack, Token } from 'aws-cdk-lib';
import { ITable } from 'aws-cdk-lib/aws-dynamodb';
import { IFunction } from "aws-cdk-lib/aws-lambda";

type energyDrinkSelectorDefinitionProps = {
    stack: Stack
    energyDrinkTable: ITable,
    sugarFreeLambdaFunction: IFunction,
    sugarLambdaFunction: IFunction
}

export const energyDrinkSelectorDefinition = ({
    stack,
    energyDrinkTable,
    sugarFreeLambdaFunction,
    sugarLambdaFunction
}: energyDrinkSelectorDefinitionProps) => {
    const rawItemSK = JsonPath.stringAt('$.sugar') === 'true' ? 'SUGAR' : 'SUGAR_FREE';
    const storeRawItem = new DynamoPutItem(stack, 'StoreRawItem', {
        item: {
            PK: DynamoAttributeValue.fromString(JsonPath.format(`RAWITEM#{}`, JsonPath.uuid())),
            SK: DynamoAttributeValue.fromString(rawItemSK),
            body: DynamoAttributeValue.fromString(JsonPath.jsonToString(JsonPath.objectAt('$'))),
        },
        table: energyDrinkTable,
        resultPath: '$.dynamoResult'
    });

    const validatePayload = new Choice(stack, 'Validate Payload');
    const isSugarFree = new Choice(stack, 'Sugar vs Sugar Free');
    const sugarFreePassState = new Pass(stack, 'Sugar Free Error', {});
    const sugarPassState = new Pass(stack, 'Sugar Error', {});
    const failState = new Fail(stack, 'Fail', {});

    const definition = storeRawItem.addCatch(failState).next(
        validatePayload
            .when(Condition.isPresent('$.sugar'), isSugarFree
                .when(Condition.booleanEquals('$.sugar', true), new LambdaInvoke(stack, 'Sugar Logic', {
                    lambdaFunction: sugarLambdaFunction,
                }).addCatch(sugarPassState, { errors: ['States.ALL'] }))
                .otherwise(new LambdaInvoke(stack, 'Sugar Free Logic', {
                    lambdaFunction: sugarFreeLambdaFunction,
                }).addCatch(sugarFreePassState, { errors: ['States.ALL'] }))
            )
            .otherwise(failState)
    )

    return definition;
};

Let’s Stack That Step

Now that we have our Step Function definition, we can turn our attention to creating a stack where our Step Function can live. In the stacks directory of the project, create a new file called EnergyDrinkSelectorStepFunctionStack.ts. Continuing the tradition we have established so far, let’s take a look at the imports we’ll need for our EnergyDrinkSelectorStepFunctionStack:

import path = require("path");
import { Construct } from "constructs";
import { NestedStack, NestedStackProps } from "aws-cdk-lib";
import { StateMachine } from "aws-cdk-lib/aws-stepfunctions";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import { Architecture, Runtime } from "aws-cdk-lib/aws-lambda";
import { ITable } from "aws-cdk-lib/aws-dynamodb";
import { ExpressStepFunction } from "../constructs/StepFunctions/ExpressStepFunction";
import { energyDrinkSelectorDefinition } from "../src/stepFunctions/definitions/energyDrinkSelector";

Let’s take a quick look at some of the imports above that we haven’t used yet in this series:

path: We’ll need this to build out some paths that are needed for our Lambda Functions
NodejsFunction: This class can be used to build a Node.js Lambda Function bundled with esbuild. There are a few reasons to use this over the Function class. One of the primary ones for us is that the NodejsFunction simplifies the development process when working with typescript.
Architecture & Runtime: These are used to specify what architecture and runtime we want our Lambda Functions to use

Next, let’s create the stack skeleton as we have previously:

type EnergyDrinkSelectorStepFunctionStackProps = NestedStackProps & {
    table: ITable;
}

export class EnergyDrinkSelectorStepFunctionStack extends NestedStack {
    constructor(scope: Construct, id: string, props: EnergyDrinkSelectorStepFunctionStackProps) {
        super(scope, id, props);

        const { table } = props;

        // fun things live in here

    }
};

In the code above, we first create a type for our props object that is passed into the stack. We take the NestedStackProps object and extend it to also contain a table parameter. Hopefully, this stack skeleton is looking quite familiar. We have the EnergyDrinkSelectorStepFunctionStack extending the NestedStack and the familiar constructor and super calls.

As we have realised, having the skeleton is great, but we want to have a bit more fun than just building a skeleton stack. Let’s look at adding some meat to this skeleton by defining our express step function and any props it may need. Remember when we created those placeholder Lambda Function handler files? Well, now we get to make use of them. Seeing as we’ll need them in our express step function and the function we created to build out the Step Function definition requires them as props, we will need to build out our Lambda Functions to pass down. We are able to do this as follows:

const sugarFreeLambdaFunction = new NodejsFunction(this, 'SugarFreeLambdaFunction', {
    entry: path.join(__dirname, '../src/functions/sugarFree/sugarFree.ts'),
    runtime: Runtime.NODEJS_18_X,
    architecture: Architecture.ARM_64,
    handler: 'sugarFree',
    bundling: {
        sourceMap: true,
        minify: true,
        tsconfig: path.join(__dirname, '../tsconfig.json'),
    },
});

const sugarLambdaFunction = new NodejsFunction(this, 'SugarLambdaFunction', {
    entry: path.join(__dirname, '../src/functions/sugar/sugar.ts'),
    runtime: Runtime.NODEJS_18_X,
    architecture: Architecture.ARM_64,
    handler: 'sugar',
    bundling: {
        sourceMap: true,
        minify: true,
        tsconfig: path.join(__dirname, '../tsconfig.json'),
    },
});

Breaking down the code above, we can see that we’re initialising the NodejsFunction class and passing it the scope (this which refers to our stack) and a logical ID. Then, in the props object, we can see we are passing an entry path. This entry path is the path to the Lambda Function handler we created earlier.

The runtime and architecture parameters allow us to choose the runtime and architecture we want the Lambda Function to run on.

The handler parameter finds the actual handler function inside the file we specified in the entry path. So, in our case, we need to specify sugarFree or sugar as these are the function names specified in the handler files.

The bundling object allows us to control how the Lambda Function is bundled, and we are able to pass our tsconfig.json file so our typescript configuration can be understood.

const energyDrinkSelectorStepFunction = new ExpressStepFunction(this, 'EnergyDrinkSelectorExpress', {
    serviceName: 'energy-drink-selector',
    stage: 'dev',
    definition: energyDrinkSelectorDefinition({
        stack: this,
        energyDrinkTable: table,
        sugarLambdaFunction: sugarLambdaFunction, 
        sugarFreeLambdaFunction: sugarFreeLambdaFunction
    })
});

this.stepFunction = energyDrinkSelectorStepFunction.stateMachine;

Initialising our custom ExpressStepFunction construct, we pass it the scope, logical ID, and props object. The serviceName and stage parameters are pretty straightforward as they’re just strings. We get to have some fun creating the definition as we can leverage our energyDrinkSelectorDefinition function. We pass it the stack, the table we destructured from our stack props object and our Lambda Functions. We then assign the stateMachine generated from the construct to a public variable in the stack to make it accessible to other things that may need it. As we’re assigning to a public variable, we need to ensure that we have declared it. We can add the following just after the start of the stack definition before the constructor call:

public readonly stepFunction: StateMachine;

So we should now have an EnergyDrinkSelectorStepFunctionStack that looks something like this:

import path = require("path");
import { Construct } from "constructs";
import { NestedStack, NestedStackProps } from "aws-cdk-lib";
import { StateMachine } from "aws-cdk-lib/aws-stepfunctions";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import { Architecture, Runtime } from "aws-cdk-lib/aws-lambda";
import { ITable } from "aws-cdk-lib/aws-dynamodb";
import { ExpressStepFunction } from "../constructs/StepFunctions/ExpressStepFunction";
import { energyDrinkSelectorDefinition } from "../src/stepFunctions/definitions/energyDrinkSelector";

type EnergyDrinkSelectorStepFunctionStackProps = NestedStackProps & {
    table: ITable;
}

export class EnergyDrinkSelectorStepFunctionStack extends NestedStack {
    public readonly stepFunction: StateMachine;

    constructor(scope: Construct, id: string, props: EnergyDrinkSelectorStepFunctionStackProps) {
        super(scope, id, props);

        const { table } = props;

        const sugarFreeLambdaFunction = new NodejsFunction(this, 'SugarFreeLambdaFunction', {
            entry: path.join(__dirname, '../src/functions/sugarFree/sugarFree.ts'),
            runtime: Runtime.NODEJS_18_X,
            architecture: Architecture.ARM_64,
            handler: 'sugarFree',
            bundling: {
                sourceMap: true,
                minify: true,
                tsconfig: path.join(__dirname, '../tsconfig.json'),
            },
        });

        const sugarLambdaFunction = new NodejsFunction(this, 'SugarLambdaFunction', {
            entry: path.join(__dirname, '../src/functions/sugar/sugar.ts'),
            runtime: Runtime.NODEJS_18_X,
            architecture: Architecture.ARM_64,
            handler: 'sugar',
            bundling: {
                sourceMap: true,
                minify: true,
                tsconfig: path.join(__dirname, '../tsconfig.json'),
            },
        });

        const energyDrinkSelectorStepFunction = new ExpressStepFunction(this, 'EnergyDrinkSelectorExpress', {
            serviceName: 'energy-drink-selector',
            stage: 'dev',
            definition: energyDrinkSelectorDefinition({
                stack: this,
                energyDrinkTable: table,
                sugarLambdaFunction: sugarLambdaFunction, 
                sugarFreeLambdaFunction: sugarFreeLambdaFunction
            }),
        });

        this.stepFunction = energyDrinkSelectorStepFunction.stateMachine;
    }
};

We’re almost ready to deploy

We now have the vast majority of elements we need to deploy our shiny new express Step Function successfully. What is left now is to ensure that these new elements are added to our EnergyDrinkSelectorStack so they are picked up when we run our deployment.

Let’s start by adding our new Step Function stack to the EnergyDrinkSelectorStack. We can do this by adding an import to the energy-drink-selector-stack.ts in the lib directory:

import { EnergyDrinkSelectorStepFunctionStack } from '../stacks/EnergyDrinkSelectorStepFunctionStack';

Once we have the import, we can then add the following line of code underneath our energyDrinkTable variable:

const stepFunctionStack = new EnergyDrinkSelectorStepFunctionStack(this, 'EnergyDrinkSelectorStepFunctionStack', { table: energyDrinkTable });

By adding this line of code, we could technically run the cdk deploy command, and everything would be synthesised and deploy fine. However, there are a few things we still need to consider.

As we want to trigger the Step Function via API Gateway, we need to ensure that API Gateway has permission to actually invoke the Step Function execution. So, we need to create an IAM role that defines what API Gateway is allowed to do. Of course, AWS CDK has constructs we can use to do this. Let’s get these imported into our energy-drink-selector-stack.ts file:

import { PolicyDocument, PolicyStatement, Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
import { AwsIntegration } from "aws-cdk-lib/aws-apigateway";

Using the constructs from the above imports, we can create a new IAM role by adding the following code:

const apiGatewayStepFunctionRole = new Role(this, 'APIGatewayStepFunctionRole', {
  assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
  inlinePolicies: {
    'StepFunctionsStartSyncExecutionPolicy': new PolicyDocument({
      statements: [
        new PolicyStatement({
          actions: ['states:StartSyncExecution'],
          resources: [stepFunctionStack.stepFunction.stateMachineArn],
        }),
      ],
    }),
  },
});

We can break down the code snippet above as follows:

new Role: This initialises the construct and we pass the scope (our stack) and a Role Name of ‘APIGatewayStepFunctionRole’
assumedBy: This allows us to set the principal that is allowed to assume the IAM role. In our case, here it is the API Gateway service so we pass the string of apigateway.amazonaws.com
inlinePolicies: This object allows us to create a new IAM policy inline in our role definition. We give the policy the name of ‘StepFunctionsStartSyncExecutionPolicy’ and then set the PolicyDocument and PolicyStatement.
PolicyDocument: Used to define the permissions and statements within the inline policy
PolicyStatement: Defines a single permission statement. In our case, it grants the action of ‘states:StartSyncExecution’ to the resources that match the ARN of our express Step Function (stepFunctionStack.stepFunction.stateMachineArn).

Now that we have the role, we need to attach it to our Step Function. We can do this by using the grantStartExecution method:

stepFunctionStack.stepFunction.grantStartExecution(apiGatewayStepFunctionRole);

The final two things we need to do to allow API Gateway to play nicely with the express Step Function we have created are:

Add an integration between the API Gateway and the step function using the StartSyncExecution action.
Add a POST method to our API to post payloads to it and trigger the Step Function.

To create the integration, we can use the AwsIntegration class. We can specify the service and action we want to use in the integration and things like the request and response templates. It looks a little something like this:

const integration = new AwsIntegration({
  service: 'states',
  action: 'StartSyncExecution',
  integrationHttpMethod: 'POST',
  options: {
    credentialsRole: apiGatewayStepFunctionRole,
    requestTemplates: {
      'application/json': `
        {
          "stateMachineArn": "${stepFunctionStack.stepFunction.stateMachineArn}",
          "input": "$util.escapeJavaScript($input.json('$'))"
        }
      `,
    },
    integrationResponses: [
      {
        statusCode: '200',
        responseTemplates: {
          'application/json': `$input.path('$.output')`,
        },
      },
      {
        statusCode: '400',
        selectionPattern: '4\\d{2}',
      },
      {
        statusCode: '500',
        selectionPattern: '5\\d{2}',
      },
    ],
  },
});

Within the options object, there are a few things we need to be aware of:

credentialsRole: This specifies the IAM role we want the API Gateway to assume. We pass it apiGatewayStepFunctionRole to ensure it has the necessary permissions for interacting with our Step Function
requestTemplates: The code here may look a little weird and scary. We are using Velocity Template Language (VTL) to dynamically insert the ARN of our Step Function and we also escape and include the JSON content of the incoming response in the ‘input’ field. This ensures that the Step Function correctly receives our payload
integrationResponses: This defines how the integration handles the different HTTP response status codes. For the 200 status code, we specify that the response body should be taken from the output field in the JSON response

Adding the new POST method is relatively straightforward, and we can do this in a few lines of code:

apiGatewayStack.restAPI.root.addMethod('POST', integration, {
  methodResponses: [
    { statusCode: '200' },
    { statusCode: '400' },
    { statusCode: '500' },
  ],
});

We access the root of our API and use the addMethod method to create a new POST request endpoint at the root of the API. We pass the integration we created to ensure that the configuration is used. An array of methodResponses is also specified, telling the API what responses we should expect from this endpoint.

Go Forth and Deploy!

Everything is now in place for us to be able to deploy and have a working API, a new Dynamo DB table, two new Lambda Functions and an Express step function! Feel free to explore the AWS console to see all the newly created resources.

You should be able to also give your sparkly new resources a test. You can test using your preferred method (e.g. in the AWS console, using an app like Postman) with a payload as follows:

{
    "sugar": true
}

Aaaaand relax

If you’re still here after covering everything we’ve covered in this episode, I tip my hat to you. We have covered a ton of stuff in this episode, so let’s have a quick recap:

Storage first!: We created a new Dynamo DB table to store the raw payloads we receive. This gives us a great audit trail to visit if we need to debug any issues.
Lambda placeholders: Two Lambda functions were created; these are just placeholders for now, but we will come back to them! These were then used within our Step Function
Express Step Function: We created a custom express Step Function construct, a definition of chained steps and then used the StateMachine construct to tie it all together
Stacks!: A new stack was created containing the Lambda Functions and the Express Step function needed in our app
API Gateway updates: Updates were made to our API to ensure it had permission to invoke the Step Function using the StartSyncExecution. This was done by creating a new IAM role and an inline IAM policy.
Invoke!: Finally, we ran through how to invoke the Step Function by sending requests to our API Gateway through the AWS console or Postman.

I think we have all earned ourselves a break after consuming so much knowledge and having so much fun with CDK in this episode. Go take a well-earned break and come back for the next episode, where we’ll be dealing with those placeholder Lambda Functions.

TL;DR

If you want to peek at the code and don’t want to read my ramblings, navigate to this Github repo and spy on everything we’ll be creating in the series.

The Energy Drink Episodes 2: The Rise of the Amazon API Gateway

Lee Priest — Tue, 14 Nov 2023 08:45:11 +0000

This post is the second part of a ‘Let’s CDK’ series. You can catch up on part 1 if you haven’t already here. This post is part of a series that will introduce you to the AWS Cloud Development Kit (CDK) and how it can be used to create an application. This series will introduce you to the core concepts of AWS CDK, how you can deploy to your AWS account, and how services like AWS Lambda Functions, DynamoDB, Step Functions and more can all be used when working with CDK.

Where were we?

In our last episode, we covered the basics of AWS CDK and key concepts like constructs, stacks and the App construct. We also ran through how to get a CDK app setup using typescript as our choice of language. Using the synth and deploy commands, we were also able to get our new CDK app deployed to our AWS account. Feel free to have a read-through of the previous episode if you need any refresher before you continue.

What next?

So, we have the basics of our app setup and deployed to our AWS account. But at the moment, we have some empty stacks with nothing really going on. While it’s great to see stacks we have created and successfully deployed to our AWS account, I’m sure we can do something more exciting.

Let’s have a think about what we’re actually trying to achieve with this app that we’re building. A good way to start the transfer from the brain to a working app is to build what’s called a ‘Logical flow’ diagram. Sheen Brisals has a great series of blog posts on ‘The Significance of Solution Design in Serverless Developments’, which I wholeheartedly recommend reading. Solution designs are definitely something that should be part of your development flow when working outside of a tutorial context, as they are invaluable to not just you but your team as a whole.

We’re not going to create a full solution design as part of this series, as we could likely have an entire series dedicated to it. However, we will employ a couple of key elements from the solution design process. Creating a logical flow diagram will give us something to refer back to during the build process to keep on track with the solution we are implementing.

Logical Flow

Above, you can see a basic diagram outlining the logical flow we want our application to have. A logical flow helps us think about what we want our app to do and what resources we could use to help us achieve it.

Let’s first start with the ‘Receive request’ step. We won’t start with the ‘User sends request step’ as we won’t be building our user. Chat GPT can’t build humans…yet. Various services could be used when thinking about the possible AWS resources we could use to handle incoming user requests. However, we don’t just want a service that the incoming request can invoke; we also want something that will enable us to follow our logical flow.

This is where we turn to the tried and true Amazon API Gateway and its many integrations. Using API Gateway, we can use services like AWS Lambda or AWS Step Functions to run logic against the payload that we receive. We can also use these integrations to return responses back to the user.

API Gateway

If you’re unfamiliar with API Gateway or want a refresher on what it is and how it works, I recommend reading about it here.

RESTful vs. WEBSOCKET API
As we don’t need to worry about real-time two-way communication like in a chat app or similar, we will build a REST API.

Access Control
As we’re not building a public API, we want to ensure we have at least some access control setup. We could go down a few different avenues when considering access control with our API Gateway REST API. For our app, we are going to use a combination of an API Key, usage plan and IAM roles and policies to ensure that we are the only ones that can access our API.

API Gateway and CDK
Before we dive in and get our hands dirty writing some cool code to generate our API via infrastructure as code, I recommend having at least a quick glance over the CDK documentation for the API Gateway construct library. I will, of course, guide you through what we are building, but it’s always good to read the documentation!

Enough talk, let’s build!

At the moment, we have the basic shell of a CDK app. Now we can get down and dirty with some code and add an API Gateway REST API. We’re going to approach this by first building our own API Gateway L3 construct. Feel free to refer back to this post for a refresher on constructs if you want.

Let’s first add a new constructs directory at the root of the project. We’ll add all our custom constructs here. We will also organise things by having a directory for each construct in reference to the AWS service they are for. As we’re going to be creating an API Gateway construct, go ahead and add an APIGateway directory inside the constructs directory.

So now your project structure should look something like this:

Creating our Construct

Now, an empty directory won’t create an API for us. So, let’s go ahead and add an APIGateway.ts file to our APIGateway directory. We will need to import a few things to create our REST API. At the top of your APIGateway.ts file, add the following:

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { ApiKey, RestApi, UsagePlan } from 'aws-cdk-lib/aws-apigateway';

Let’s take a quick look at what we have just imported:

Stack: This is a root construct that represents a single CloudFormation stack. Remember, we need to scope our construct to a Stack, so this will be needed.
Construct: We are going to be creating our own APIGateway Construct so we will be extending the core Construct class.
ApiKey: This is needed so we can generate an API Key
RestApi: The class that represents a REST API in API Gateway. This is what we’ll use to create our API.
UsagePlan: This will work with the API key to specify who can use the API and how much they can call it.

Now we have our imports sorted, let’s create the shell of our custom APIGateway construct:

export class APIGateway extends Construct {
    constructor(scope: Stack, id: string, props: APIGatewayProps) {
        super(scope, id);

        // This is where we're gonna have some fun!        

    }
}

This is the bare bones of our APIGateway Construct. You can see we’re extending the Construct class and initialising it with the constructor. Three arguments are also passed into the constructor:

scope: This is the scope the Construct is assigned to. In our case, it will be the Stack it sits within.
id: A string that represents a logical ID for the Construct
props: An object with any useful properties that can help us define our new Construct

The keen-eyed among you will have also noticed the props being typed as APIGatewayProps. We can go ahead and create the type as:

type ApiGatewayProps = {
    serviceName: string;
    stage: string;
    rateLimit?: number;
    burstLimit?: number;
}

Passing the serviceName and stage down as part of the props object allows the Construct to be more easily used across different stacks we may have. We can also use the stage variable to differentiate across deployment environments. Setting the rateLimit and burstLimit as optional allows us to specify defaults inside the Construct but also override if needed by a particular stack.

Creating the API

Let’s start adding the main logic of our custom Construct by destructuring variables from our props object and initialising the RestApi class to create our API:

export class APIGateway extends Construct {
    public readonly restAPI: RestApi;

    constructor(scope: Stack, id: string, props: ApiGatewayProps) {
        super(scope, id);

        const {
            serviceName,
            stage,
            rateLimit = 100000,
            burstLimit = 1000
        } = props;

        this.restAPI = new RestApi(this, `${serviceName}-restAPI-${stage}`, {
            deployOptions: {
                stageName: stage
            },
            defaultMethodOptions: {
                apiKeyRequired: true
            }
        });
    }
}

The code above is actually all you really need to create a REST API using AWS CDK. However, we don’t have any methods attached to the API, so we would run into an issue when deploying. Fear not! We will rectify this soon. Above, we destructured our variables from the props object and set the defaults for the rateLimit and burstLimit properties. Then, we initialised the RestApi class.

We have passed three arguments to the RestApi class:

The scope for the RestAPI
A logical ID
A props object

We use the serviceName and stage variables to create the logical ID for the RestApi. Within the props object, we specify two things:

deployOptions: Settings for the API Gateway stage that link to the latest deployment when activated. We set the stageName using the stage variable so we can easily see what environment
defaultMethodOptions: Method options to use for all methods created within this API. We specify that apiKeyRequired is true. This means all methods created in this API will require an API key to be present in the request.

We also specify a public readonly property on the construct and have this equal to the API. We do this to easily access the API outside of the construct and add methods to the API when needed.

Creating our API Key

So, we’ve got our API setup and have specified that all methods in that API must have an API key present in the request. We should probably create an API key, so we’re able to actually use the API. Luckily, this is nice and easy within CDK world:

const apiKey = new ApiKey(this, `${serviceName}-apiKey-${stage}`, {
  apiKeyName: `${serviceName}-apiKey-${stage}`,
  generateDistinctId: true,
  stages: [this.restAPI.deploymentStage],
});

Using the ApiKey construct we imported earlier. We can pass in the scope, logical ID, and props object to create an API key. Looking at the props object we passed to the ApiKey construct, we can see:

apiKeyName: A string that is set as the name for the API Key
generateDistinctId: A boolean value that, when set to true, ensures that the name of the API key is different to the API key name.
stages: An array of stages that the API key is associated with. We set this to the deploymentStage of the API.

We now have our API key! Woohoo!

Creating our Usage Plan

API? Check. API Key? Check. We can call it a day now, right? Not so fast! We still need to create our usage plan. If you aren’t familiar with usage plans, I recommend having a read over the documentation. As mentioned above, our usage plan will allow us to control and monitor access to our API. We can make use of our rateLimit and burstLimit variables we saw earlier and also link API stages to it.

To create our usage plan, we can do the following:

const usagePlan = new UsagePlan(this, `${serviceName}-usagePlan-${stage}`, {
    name: `${serviceName}-${stage}`,
    throttle: {
        rateLimit,
        burstLimit
    },
    apiStages: [{
        stage: this.restAPI.deploymentStage
    }]
});

Using the UsagePlan construct we imported, we can pass the scope, logical ID and props object (are you noticing a pattern yet?). Within the props object, we specify the following:

name: The name given to our usage plan. Using the variables passed via the props object. We can ensure these are dynamic and related to the correct scope.
throttle: The rate limit and burst limit we want to set to ensure traffic to the API doesn’t hit a limit we don’t want. You can read more here on API request throttling

Don’t forget!

We have our API key and usage plan, but we need to ensure that we add the API key to the usage plan. If we don’t, we’ll have these two resources floating around in our account, with the API key just acting as an identifier without any benefit of the usage plan. Luckily, this is incredibly easy to do:

usagePlan.addApiKey(apiKey);

Here’s One I Made Earlier

Bringing all the pieces we create above together, we should have a custom APIGateway construct that looks like this:

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { ApiKey, RestApi, UsagePlan } from 'aws-cdk-lib/aws-apigateway';

type ApiGatewayProps = {
    serviceName: string;
    stage: string;
    rateLimit?: number;
    burstLimit?: number;
}

export class APIGateway extends Construct {
    public readonly restAPI: RestApi;

    constructor(scope: Stack, id: string, props: ApiGatewayProps) {
        super(scope, id);

        const {
            serviceName,
            stage,
            rateLimit = 100000,
            burstLimit = 1000
        } = props;

        this.restAPI = new RestApi(this, `${serviceName}-restAPI-${stage}`, {
            deployOptions: {
                stageName: stage
            },
            defaultMethodOptions: {
                apiKeyRequired: true
            }
        });

        const apiKey = new ApiKey(this, `${serviceName}-apiKey-${stage}`, {
            apiKeyName: `${serviceName}-apiKey-${stage}`,
            generateDistinctId: true,
            stages: [this.restAPI.deploymentStage],
        });

        const usagePlan = new UsagePlan(this, `${serviceName}-usagePlan-${stage}`, {
            name: `${serviceName}-${stage}`,
            throttle: {
                rateLimit,
                burstLimit
            },
            apiStages: [{
                stage: this.restAPI.deploymentStage
            }]
        });

        usagePlan.addApiKey(apiKey);
    }
}

Let’s get Stacking

Now that we have our own custom APIGateway construct. We can use it in our stacks. If you had a browse around the app that was created by running the cdk init command we ran in the previous episode, you would have seen the EnergyDrinkSelectorStack within the energy-drink-selector.ts file in the lib directory. This stack gets imported into the App within the energy-drink-selector.ts file in the bin directory. Then, when a deployment is run, it all gets magically transformed into a Cloudformation and then turned into the AWS resources we defined.

The approach we are going to use in this series is to use CDK nested stacks. “What are nested stacks?!” I hear you cry. Well, the clue is partially in the name. A nested stack is basically a child stack of a parent stack. So we can have stacks within stacks. Don’t worry. It sounds more confusing than it is in practice. For us, the EnergyDrinkSelectorStack will be our parent stack, and within this stack, we will define our child stacks. You can read more about nested stacks here.

Creating an APIGatewayStack

Earlier, we created a new constructs directory for our custom constructs. Let’s do the same for our stacks. We can go ahead and create a stacks directory in the root of the project. Within this new directory, we can create an APIGatewayStack.ts file to house the code for our API Gateway stack.

Let’s start our stack creation by handling our imports first:

import { NestedStack, NestedStackProps } from "aws-cdk-lib";
import { Construct } from "constructs";
import { APIGateway } from "../constructs/APIGateway/APIGateway";
import { RestApi } from "aws-cdk-lib/aws-apigateway";

Let’s take a quick look at these imports:

NestedStack: The CDK construct we use to create a nested stack
NestedStackProps: A type interface for the initialisation props for the NestedStack
Construct: The scope of the NestedStack will be a Construct, as Stacks are Constructs, and we will be scoping this stack to our main EnergyDrinkSelectorStack
APIGateway: This is the custom APIGateway construct we created
RestApi: We will be using this to ensure type safety with the public readonly property we will add to our stack

We’ve got our imports sorted. Let’s create the actual stack:

export class APIGatewayStack extends NestedStack {
    public readonly restAPI: RestApi;

    constructor(scope: Construct, id: string, props?: NestedStackProps) {
        super(scope, id, props);

        const apiGateway = new APIGateway(this, 'EnergyDrinkSelectorAPI', {
            serviceName: 'energy-drink-selector',
            stage: 'dev',
        });

        this.restAPI = apiGateway.restAPI;
    }
};

With the code above, we can see that we have used our custom APIGateway construct and passed in stack-specific values for the props. We can also see that we’re setting the public property equal to the restAPI we create in the construct, allowing us to add methods where needed.

Last Step…I Promise

We have our custom APIGateway construct and our custom APIGatewayStack, so what’s left? Well, we need to make sure that we are making use of these within our main EnergyDrinkSelectorStack as that’s the one that is passed to the App that’s then used to synthesise the Cloudformation template used to create the AWS resources.

In our energy-drink-selector-stack.ts in the lib directory, all we need to do is import our APIGatewayStack and add a method to the API for CDK to allow us to deploy. We can do this as follows:

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { APIGatewayStack } from '../stacks/APIGatewayStack';

export class EnergyDrinkSelectorStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const apiGatewayStack = new APIGatewayStack(this, 'EnergyDrinkSelectorAPIGatewayStack');
    apiGatewayStack.restAPI.root.addMethod('GET');
  }
}

In the code above, you can see that we import our custom APIGatewayStack, initialise it and store it in an apiGatewayStack variable. We then add a GET method to the API to satisfy the deployment requirement of having at least one method on the API.

Go Forth and Deploy!

With all the pieces of the puzzle now in place to create our very own REST API in API Gateway via CDK, we can run cdk deploy, and as if by magic, we should have a brand new shiny API waiting for us in the AWS console.

Aaaaand relax

We covered quite a lot in this episode. Kudos for sticking with it and making it through! Let’s have a quick recap of what we covered:

Logical Flow diagram: We took some inspiration from the realm of the solution design and created a logical flow diagram to help us focus on what we wanted to achieve
API Gateway: We looked at some points around API Gateway in relation to the app we’ll be building. We decided on a RESTful API over a WEBSOCKET API as we don’t need the two-way communication functionality that WEBSOCKET APIs offer.
Access control: We covered things like API Keys and Usage Plans to ensure that we can both lock down and limit API usage.
Custom Construct: We created our own custom construct! An L3 construct that allows us to create a REST API in API Gateway
Nested stacks: We created a stack using the NestedStack construct, allowing us to have child stacks within a parent stack

With all this newly acquired knowledge swirling around in your brain, I’d recommend having another look over the code and familiarising yourself with the syntax and patterns used, as we’ll be seeing similar patterns in the upcoming episodes.

I think you’ve earned a rest after all this fun! Go grab a beverage and a snack, and then start preparing for our next episode, which will focus on a little service called Step Functions.

TL;DR

If you want to peek at the code and don’t want to read my ramblings, navigate to this Github repo and spy on everything we’ll be creating in the series.

Let’s CDK: The Energy Drink Episodes

Lee Priest — Mon, 06 Nov 2023 10:12:00 +0000

Ever since I started my foray into the world of Serverless, I have mainly worked with Serverless Framework for my day-to-day development tasks. Don’t get me wrong; I have no beef with Serverless Framework; it has served me well while using it.

However, it appears that there is a not-so-new kid on the block that has caught my attention. Enter AWS Cloud Development Kit (CDK).

This post is part of a series that will introduce you to AWS CDK and how it can be used to create an application. This series will introduce you to the core concepts of AWS CDK, how you can deploy to your AWS account, and how services like AWS Lambda Functions, DynamoDB, Step Functions and more can all be used when working with CDK.

AWS CD...What?

Rather than writing my own description of what AWS CDK is, I will borrow from AWS’ FAQ page to explain:

The AWS Cloud Development Kit (AWS CDK) is an open-source software development framework for defining cloud infrastructure as code with modern programming languages and deploying it through AWS CloudFormation.

So, what does that really mean? I look at CDK in a similar way to LEGO bricks and sets. AWS CDK provides us with a bunch of base plates and bricks that allow us to build our super cool space stations or, in this case, serverless infrastructure. CDK provides us with many really cool constructs to leverage to create things we all know and love, like API Gateway, Lambda Functions and much more. You can find the documentation for CDK here. It is worth looking at, even if you only glance over it to see how much it provides.

Constructs = Building blocks

Although it’s a scary-sounding word, constructs in CDK are the basic building blocks of an AWS CDK application. To continue with our LEGO likeness, let’s imagine that we have the awesome T. rex Breakout set in front of us. We open the box and notice that the fence in the background and the enclosure plinth are already built for us, saving us some time and meaning we’re not building everything from scratch. This is basically how we can look at Constructs in CDK.

A CDK Construct is basically our pre-made T. Rex enclosure plinth

Construct types
Another scary-sounding idea, I know, but fear not! Constructs in CDK are split into three different types:

L1 Constructs:

Official definition: An L1 construct is the exact resource CloudFormation defines. Using a Cfn prefix, these constructs are basic and must be manually configured.

Our LEGO analogy explanation: These are our individual LEGO bricks. They are very basic, small pieces that aren’t much on their own. But are the foundation for our set.

L2 Constructs:

Official definition: An L2 construct has common boilerplate code and logic. They come with default configurations and commonly combine corresponding L1 constructs.

Our LEGO analogy explanation: Think back to that pre-made enclosure plinth. An L2 construct is a lot like that. It contains a bunch of L1 constructs (basic bricks) but has a default configuration to be the shape of the plinth.

L3 Constructs:

Official definition: Also called a pattern, these are designed to help complete full tasks. They involve multiple kinds of resources and are much more specific and opinionated in their configuration than an L2 construct.

Our LEGO analogy explanation: Remember that enclosure plinth? This is where it’s specified that it’s for the T. Rex. The opinionated and specific configuration designates this plinth for the T. Rex enclosure. We can see the L1 in the bricks and the L2 in the plinth itself with the specific config of the L3 setting us up with that T. Rex specificity.

Piecing it together

So far, we’ve looked at constructs in AWS CDK. You might wonder, ‘Do these constructs just float around and somehow interact?’. The answer to that is no. Constructs in CDK typically sit within what is called a ‘Stack’.

A stack is a unit of deployment and has resources defined within its scope, either directly or indirectly.

We can easily identify multiple stacks if we return to our beloved Jurassic Park T. Rex Lego set. We could see stacks for the T. Rex, the cars, the fence and greenery, the baseplate, etc. If we take the T. Rex, for example, we can see the stack being structured as follows:

import { Construct } from 'constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { LogGroup } from 'aws-cdk-lib/aws-logs';
import { Bucket} from 'aws-cdk-lib/aws-s3';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { EventBus } from 'aws-cdk-lib/aws-events';
import { StateMachine } from 'aws-cdk-lib/aws-stepfunctions';

export class TRexStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Head = Lambda Function
    new NodejsFunction(this, 'HeadLambdaFunction');

    // Body = S3 Bucket
    new Bucket(this, 'BodyBucket');

    // Tail = Cloudwatch log group
    new LogGroup(this, 'TailLogs');

    // Arms = Eventbridge event bus
    new EventBus(this, 'ArmsEventBus');

    // Legs = Step Function
    new StateMachine(this, 'LegsStateMachine', {
      // the definition of our state machine with our tasks etc.
      definition
    });
  }
}

The code example above defines a ‘TRexStack’, which extends the base Stack construct. This encapsulates a bunch of other constructs that define things like a Lambda Function, S3 bucket, Log group, etc. So basically, a Stack can be thought of as:

A stack of building blocks that together form a part of your application

We need a box to put it all in

Our CDK application needs a box or a ‘container’ as with our LEGO set. In the context of CDK, an App acts as a container for one or more stacks. Note: When I mention ‘container,’ I don’t mean a docker container or similar. It acts as a wrapper that serves as each stack’s scope. Having the App construct serve each stack the same scope makes it easy for different Stacks to refer to each other's resources. If we refer back to our T. Rex set, the App would be the box with all the pieces and the instruction manual contained inside it.

import { App, Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { TRexStack } from './stacks/TRexStack';
import { CarsStack } from './stacks/CarsStack';
import { FenceStack } from './stacks/FenceStack';
import { MiniFiguresStack } from './stacks/MiniFiguresStack';
import { BasePlateStack } from './stacks/BasePlateStack';

const app = new App();

export class TRexBreaksOutStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // T. Rex Stack
    new TRexStack(this, 't-rex-ID');

    // Cars Stack
    new CarsStack(this, 'cars-ID');

    // Fence Stack
    new FenceStack(this, 'fence-ID');

    // Mini Figures Stack
    const miniFiguresStack = new MiniFiguresStack(this, 'mini-figures-ID');
    const miniFiguresStackDrGrantPath = miniFiguresStack.versionedBasePath.addResource('dr-grant');
    // Base Plate Stack
    new BasePlateStack(this, 'base-plate-ID', {
      // We can pass resources from one stack to another!
      drGrantPath: miniFiguresStackDrGrantPath
    });
  }
}

new TRexBreaksOutStack(app);

In the code example above, you can see that we create a new app and then define the construct where the app is used as the parent scope. The code example above could be deployed to an AWS account, and the resources would be created. There are two main commands we need to be aware of when it comes to deployments:

cdk synth — This command executes your app, which causes the resources defined within it to be transformed into a CloudFormation template. A YAML-format template is
cdk deploy — As the name suggests, this command deploys the resources to your AWS account. This command will also synthesize your app before running the deployment to ensure that it is the latest version of your code that is being deployed.

What’s this got to do with energy drinks?

I have waffled on at you for long enough about CDK, what it is, how we can deploy it, etc. But sometimes it’s more fun and easier to learn if we get our hands dirty and build something ourselves. So, I thought it would be fun if we took the application I mentioned in my previous post here and built it using CDK.

I won't force you to read that previous post, although it would be awesome if you did! So here’s an outline of what the app is and needs to do:

What it is:
An application that helps the user choose which energy drink they should drink.

What it needs to do:
The application will need to be able to receive a POST request, run some logic based on that POST request and then return to the user information about the energy drink they should choose.

Before we get started

I write code in TypeScript and will be running through this build using it. However, you can use any other language you like, provided AWS CDK supports it. If you are bored of me and want to run through a different tutorial on getting started with CDK, AWS have a great one here.

If you are still here and willing to put up with me, there are some things you will need before you can start the build. These are:

Node.js version 14.15.0 or later — You can find download links here.
An installation of TypeScript — You can run npm -g install typescript to install it globally on your machine.
Authentication with AWS — Instructions for this can be found on this page. This establishes how AWS CDK authenticates with the AWS services, allowing code deployment and other things.
AWS CDK — You can run npm install -g aws-cdk to install it globally on your machine.

If you are using VS Code, the AWS toolkit for VS Code is helpful when working with CDK and AWS.

Let’s get started!

We’ve gone through a lot so far in this post. Kudos to you for making it this far! So, for this first episode, we will run through the process of setting up the CDK app and deploying it to an AWS account.

First, let’s open up the terminal and either navigate to a directory you want to create the app in or create a new directory to create the app in. Let’s create a new directory and then jump into it by running the following in the terminal:

mkdir energy-drink-selector
cd energy-drink-selector

So now we’re in the energy-drink-selector directory, we can start setting up all the files and creating all the directories we need, right? Luckily, AWS has simplified the creation of a CDK app into a single command that we can run. This command is:

cdk init app --language typescript

Running this command in our energy-drink-selector directory will set up some files and folders to use as a base for creating the rest of our application. I recommend exploring what was generated and getting a feel for the code within it.

Let's add esbuild as a dependency, this will be needed in future episodes when running deployments. We can do this by running the following command in the project root:

npm i esbuild

As we now have a basic CDK application, we can deploy it to our AWS account. Let’s first synthesize the app by running:

cdk synth

This will create a YAML-format CloudFormation template and an output of our app in a cdk.out directory. We can then deploy our application to our AWS account using the command:

cdk deploy

You will see a progress bar as the stack within the application is deployed. Once the deployment has finished, you will be able to open your AWS console, navigate to CloudFormation, and you will be able to see the EnergyDrinkSelector stack.

Aaaaand relax

With that, you have successfully created and deployed your first CDK app! We have run through quite a lot in this post, so let's have a quick recap before we call it a day and re-energise. We covered:

What is CDK — Amazon Cloud Development Kit — An open-source framework for defining cloud infrastructure as code and deploying it through AWS CloudFormation
Constructs and their types — A construct is a basic building block of a CDK application. They come in types including L1, L2 and L3. These types essentially describe how much boilerplate code there is and how opinionated the construct is.
Stacks and the ‘App’ — A stack is a ‘unit of deployment’ which consists of one or many constructs, with the App being the parent ‘container’ that serves as the scope for each Stack.

Going forward, we will work with several AWS services such as API Gateway, DynamoDB, Step Functions and more! So stay tuned for the next episode, and go grab a much-deserved can of liquid energy! (or whichever type of beverage you prefer).