Skip to main content

Cloud Development Kit

The AWS Cloud Development Kit (CDK) is an Infrastructure-as-Code (IaC) tool using general-purpose programming languages such as TypeScript/JavaScript, Python, Java, and .NET to programmatically define your cloud architecture on AWS.

AWS CDK CLI for LocalStack​

cdklocal is a thin wrapper script for using the AWS CDK library against local APIs provided by LocalStack.

Installation​

The cdklocal command line is published as an npm library:

# Install globally
npm install -g aws-cdk-local aws-cdk

# Verify it installed correctly
cdklocal --version
# e.g. 1.65.5
note

Using cdklocal locally (e.g. within the node_modules of your repo instead of globally installed) does not work at the moment for some setups, so make sure you install both aws-cdk and aws-cdk-local with the -G flag.

Usage​

cdklocal can be used as a drop-in replacement of where you would otherwise use cdk when targeting the AWS Cloud.

$ cdklocal --help

Configuration​

The following environment variables can be configured:

  • AWS_ENDPOINT_URL: The endpoint URL (i.e., protocol, host, and port) to connect to LocalStack (default: http://localhost:4566)
  • LAMBDA_MOUNT_CODE: Whether to use local Lambda code mounting (via setting hot-reload S3 bucket name)

Example​

Make sure that LocalStack is installed and successfully started with the required services before running the example

$ curl http://localhost:4566/_localstack/health

The CDK command line ships with a sample app generator to run a quick test for getting started.

# create sample app
mkdir /tmp/test; cd /tmp/test
cdklocal init sample-app --language=javascript

# bootstrap localstack environment
cdklocal bootstrap

# deploy the sample app
cdklocal deploy
> Do you wish to deploy these changes (y/n)? y

Once the deployment is done, you can inspect the created resources via the awslocal command line

$ awslocal sns list-topics
 {
     "Topics": [
         {
             "TopicArn": "arn:aws:sns:us-east-1:000000000000:TestStack-TestTopic339EC197-79F43WWCCS4Z"
         }
     ]
}

Limitations​

Stacks with validated certificates​

By default, stacks with validated certificates may not be deployed using the local lambda executor. This originates from the way how CDK ensures the certificate is ready - it creates a single-file lambda function with a single dependency on aws-sdk which is usually preinstalled and available globally in lambda runtime. When this lambda is executed locally from the /tmp folder, the package can not be discovered by Node due to the way how Node package resolution works.