Using The AWS CDK With LocalStack And aws-cdk-local

We will explore how we can make use of LocalStack and LocalStack's wrapper package aws-cdk-local to speed up our local development.

This post will build off the work that in my AWS CDK With TypeScript Foundations blog post.

Source code can be found here.

Prerequisites

This blog post will operate as if you have a pro LocalStack account, however it will also work on the free tier.

Getting started

Clone the working repo from the previous blog post and add some files for our LocalStack config.

# Clone and change into the working directory
$ git clone https://github.com/okeeffed/aws-cdk-with-typescript-foundations using-the-aws-cdk-with-localstack-and-aws-cdk-local
$ cd using-the-aws-cdk-with-localstack-and-aws-cdk-local

# Install the modules
$ npm install
# Add aws-cdk-local
$ npm i --save-dev aws-cdk-local

# Create docker-compose.yml file for LocalStack
$ touch docker-compose.yml
copy

At this stage, we are ready to add our docker-compose.yml config and start up LocalStack.

Starting up LocalStack

Add the following to your docker-compose.yml file:

version: "2.1"
services:
  localstack:
    image: localstack/localstack
    ports:
      - "53:53"
      - "443:443"
      - "4510-4520:4510-4520"
      - "4566-4620:4566-4620"
      - "${PORT_WEB_UI-8080}:${PORT_WEB_UI-8080}"
    environment:
      - LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY}
      - HOSTNAME_EXTERNAL=localstack
      - DEBUG=1
      - DATA_DIR=/tmp/localstack/data
      - DOCKER_HOST=unix:///var/run/docker.sock
      - LAMBDA_EXECUTOR=docker
      - LAMBDA_NETWORK=bridge
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    tmpfs:
      - /tmp/localstack:exec,mode=600
copy

Most of this config comes from the LocalStack documentation, but it is important to note that LOCALSTACK_API_KEY is an exported environment variable that I have available at runtime.

You can also add this to a local .env file.

To startup LocalStack, run docker compose up and let it does its things.

To check things are running, we can ping the port 4566:

$ curl http://localhost:4566
# {"status": "running"}
copy

Updating our infrastructure to use AWS CDK Local

Once Docker is up and running, we need to amend our project code to allow for us to use aws-cdk-local.

To do so, we need to add the following to our package.json file under scripts:

"scripts": {
    "local": "cdklocal"
},
copy

That's it! The cdklocal command is a wrapper around aws-cdk that points the actions of the CDK to the local 4566 port used by LocalStack.

Deploying our stack to LocalStack

Everything from our previous post has the code ready to deployed, so we can work through our lifecycle of synth and deploy but with the caveat that we use the local script:

$ npm run local synth

> aws-cdk-with-typescript-foundations@0.1.0 local
> cdklocal "synth"

Resources:
  MyFirstBucketB8884501:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: hello-aws-cdk-my-first-bucket
    UpdateReplacePolicy: Delete
    DeletionPolicy: Delete
    Metadata:
      aws:cdk:path: AwsCdkWithTypescriptFoundationsStack/MyFirstBucket/Resource
  CDKMetadata:
    Type: AWS::CDK::Metadata
    Properties:
      Analytics: v2:deflate64:H4sIAAAAAAAAEyWNSwrDMAxEz9K9o9SU0C5Lc4P0BEFWwTGVwJLThfHdm89qHswbxoP3d7henvNPOwypryiZoL5txuRGYbVc0Nz44YlUSkbaeStCtCjc3D7UG9RXwUSHeFJrjiUQLNqvfoDHdrJojF0ubPFLMJ35BzafENSBAAAA
    Metadata:
      aws:cdk:path: AwsCdkWithTypescriptFoundationsStack/CDKMetadata/Default
    Condition: CDKMetadataAvailable
Conditions:
  CDKMetadataAvailable:
    Fn::Or:
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - af-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-northeast-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-northeast-2
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-southeast-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-southeast-2
          - Fn::Equals:
              - Ref: AWS::Region
              - ca-central-1
          - Fn::Equals:
              - Ref: AWS::Region
              - cn-north-1
          - Fn::Equals:
              - Ref: AWS::Region
              - cn-northwest-1
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-central-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-north-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-2
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-3
          - Fn::Equals:
              - Ref: AWS::Region
              - me-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - sa-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - us-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - us-east-2
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - us-west-1
          - Fn::Equals:
              - Ref: AWS::Region
              - us-west-2
copy

We are now ready to deploy:

$ npm run local deploy

> aws-cdk-with-typescript-foundations@0.1.0 local
> cdklocal "deploy"

AwsCdkWithTypescriptFoundationsStack: deploying...
AwsCdkWithTypescriptFoundationsStack: creating CloudFormation changeset...


 ✅  AwsCdkWithTypescriptFoundationsStack

Stack ARN:
arn:aws:cloudformation:us-east-1:000000000000:stack/AwsCdkWithTypescriptFoundationsStack/ec2cbb64
copy

Seeing our new bucket locally

We can now check our bucket was deployed successfully through the AWS CLI. You have two choices:

I am going to use the latter in this demonstration as it is just a thin wrapper around the AWS CLI:

$ awslocal s3 ls | grep hello-aws-cdk-my-first-bucket
2021-08-07 08:10:53 hello-aws-cdk-my-first-bucket
copy

Awesome! We can see our bucket is available locally.

Tearing down our local stack

As per usual, we can go through the process of tearing down the local stack (or simply stopping the Docker containers).

For now, let's get into the habit of a proper teardown via the CDK:

$ npm run local destroy

> aws-cdk-with-typescript-foundations@0.1.0 local
> cdklocal "destroy"

Are you sure you want to delete: AwsCdkWithTypescriptFoundationsStack (y/n)? y
AwsCdkWithTypescriptFoundationsStack: destroying...

 ✅  AwsCdkWithTypescriptFoundationsStack: destroyed

$ awslocal s3 ls | grep hello-aws-cdk-my-first-bucket
# no grep output
copy

Summary

Today's post demonstrated how to use LocalStack to work on a local AWS environment.

LocalStack significantly improves development time for infrastructure (where supported) and is a great tool all around with an active community.

I highly recommend giving it a go. I will be using LocalStack behind the scenes where I can for the upcoming blog posts to test locally.

Resources and further reading

Photo credit: rishabh