AWS CDK
Overview
Section titled “Overview”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
Section titled “AWS CDK CLI for LocalStack”cdklocal
is a thin wrapper script for using the AWS CDK library against local APIs provided by LocalStack.
Installation
Section titled “Installation”The cdklocal
command line is published as an npm library:
# Install globallynpm install -g aws-cdk-local aws-cdk
# Verify it installed correctlycdklocal --version# e.g. 1.65.5
cdklocal
can be used as a drop-in replacement of where you would otherwise use cdk
when targeting the AWS Cloud.
cdklocal --help
Configuration
Section titled “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 settinghot-reload
S3 bucket name)
Example
Section titled “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 appmkdir /tmp/test; cd /tmp/testcdklocal init sample-app --language=javascript
# bootstrap localstack environmentcdklocal bootstrap
# deploy the sample appcdklocal 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" } ]}
Current Limitations
Section titled “Current Limitations”Updating CDK stacks
Section titled “Updating CDK stacks”Updating CDK stacks may result in deployment failures and inconsistent state within LocalStack.
It is advisable to prioritize re-creating (deleting and re-deploying) over updating stacks.
Our focus for this year will be on resolving issues related to the UPDATE
support, and continuous improvements can be anticipated in this area throughout 2024.
Stacks with validated certificates
Section titled “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.
CDK Version Compatibility
Section titled “CDK Version Compatibility”cdklocal
works with all installed versions of the Node.js aws-cdk
package.
However, issues exist for aws-cdk >= 2.177.0
.
For these versions:
- We unset AWS-related environment variables like
AWS_PROFILE
before callingcdk
. - We explicitly set
AWS_ENDPOINT_URL
andAWS_ENDPOINT_URL_S3
to point to LocalStack.
Some environment variables may cause conflicting config, such as wrong region or accidental deploys to real AWS.
To allow specific variables (e.g., AWS_REGION
), use AWS_ENVAR_ALLOWLIST
:
AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...
If you manually set AWS_ENDPOINT_URL
, it will be used.
You must also set AWS_ENDPOINT_URL_S3
, and it must include .s3.
to correctly identify S3 API calls.
See full configuration details on our configuration docs.