AWS Marketplace

Accelerating software delivery using LocalStack Cloud Emulator from AWS Marketplace

In today’s fast-paced digital transformation landscape, businesses are constantly seeking ways to optimize their software delivery processes, embrace DevOps methodologies, and foster agility to stay ahead of the competition. While the cloud presents opportunities for innovation and running your applications at scale, you can experience long build times, protracted continuous integration (CI) waiting periods, and a cumbersome developer experience, resulting in slow development and testing cycles. Additionally, organizations face the dilemma of providing adequate cloud access to engineers during their onboarding without compromising security and incurring unnecessary costs due to misconfigurations or inefficiencies. To counter these challenges and bolster the application of DevOps methodologies especially in security and testing it’s essential to shift focus toward strategies that facilitate moving faster.

LocalStack addresses these challenges head-on. LocalStack enables seamless local development and testing of cloud applications by providing a local sandbox environment that emulates over 90 Amazon Web Services (AWS) services. This empowers developers to build, configure, and validate their cloud applications and infrastructure deployments locally. With LocalStack, new engineers can swiftly familiarize themselves with AWS and experiment with real-world scenarios, promoting faster on-boarding and reducing dev and test loops that can burden software development and delivery workflows. Moreover, it allows you to truly shift left, and be productive with testing, debugging, and profiling your cloud applications.

LocalStack enables deploy times for cloud and serverless applications from minutes to seconds locally and in continuous integration and continuous delivery (CI/CD) environments. With instant feedback for any application changes, LocalStack’s Cloud Emulator boosts your productivity and significantly reduces risk and complexity because engineers operate within a local environment where mistakes are easier to correct. The efficiency and reduced waiting times for resource provisioning and testing help to maximize engineers’ productivity, a critical factor in optimizing costs associated with their time and expertise. Furthermore, LocalStack empowers developers to innovate faster and collaborate effectively in airtight environments, fuelling a culture of agility and DevOps excellence.

This blog post shows you how to set up LocalStack on your local developer machine. This allows you to test AWS Cloud Development Kit (AWS CDK) projects without needing access to the actual AWS cloud. We explain how to integrate LocalStack with tools like the AWS Command Line Interface (AWS CLI) and AWS CDK. This lets you get started with a fully local cloud development environment, without having to maintain additional tooling.

How LocalStack works to emulate cloud services locally

Prerequisites

To start testing your AWS CDK configurations with LocalStack, you need to install the following software on your machine:

  • AWS CLI
  • AWS CDK and cdklocal package
  • Docker
  • Node.js & npm
  • Python 3.10 & pip

Note: The instructions for this blog are tested on Mac and Linux machines, you might need to modify some of the commands to run on windows machines.

LocalStack ships as a Docker container and can run stacks with one to hundreds or more AWS services on a developer laptop or on a continuous integration server. LocalStack is compliant with AWS service APIs, and therefore compatible with most AWS client software, including AWS CDK, AWS CloudFormation, Terraform, Pulumi, and others. The open-source ecosystem of AWS makes this possible. The Smithy specification language, the botocore service specification parser, and AWS Lambda runtime images provided by AWS are all tools that LocalStack uses to provide service parity with AWS.

LocalStack includes a large and growing registry of AWS service emulators. Some service emulators use additional open-source software. For example: LocalStack’s implementation of Amazon Relational Database Service (Amazon RDS) starts a PostgreSQL or MariaDB server inside the container. Other, more sophisticated examples, including big data services like AWS Glue or Amazon Athena, use Apache Spark, Hive, or Hadoop.

To demonstrate the functionalities of LocalStack, you can emulate AWS commands against the local infrastructure using  AWS CLI with a localstack profile:

  1. Create an account on the LocalStack Web Application and sign up for a free trial. Once you logged in, retrieve your Auth Token from the Getting Started You can use the Auth Token to activate your LocalStack Docker container and the cloud emulator on your local machine.
  2. Configure the LocalStack Auth Token and an AWS profile for LocalStack. To configure the LocalStack Auth Token, pull the localstack/localstack-pro image to start LocalStack Pro services (such as Amazon EMR, Amazon Athena, or Amazon Elastic Container Service (Amazon ECS)) and export the Auth Token to your terminal by replacing <your key> with your Auth Token:

docker pull localstack/localstack-pro

export LOCALSTACK_AUTH_TOKEN=<your auth token>

  1. Set up an AWS profile for LocalStack. Install AWS CLI and add the following to your ~/.aws/config file:
[profile localstack]
region=us-east-1
output=json
  1. Add the following to your ~/.aws/credentials file:
[localstack]
aws_access_key_id=test
aws_secret_access_key=test

Note: You may also use ‘aws configure’ command to set up the AWS localstack profile.

  1. Install the localstack CLI:

pip install localstack

Note: If you don’t prefer using pip, you can install LocalStack as a binary on your respective operating system. You can follow the documentation on installing the localstack CLI.

  1. After it’s installed, start LocalStack on your machine by running the following command:

localstack start -d

After LocalStack is started, the local AWS APIs will be available on localhost:4566, which functions as the edge port. All LocalStack wrapper scripts and API calls redirect the AWS requests to this port for the LocalStack emulator to process.

  1. Run some basic AWS CLI commands to check if the installation is working correctly. Try the following commands to create a local S3 bucket:

aws s3 mb s3://test --profile localstack --endpoint-url=http://localhost:4566

  1. Run the following commands to add a file to the local S3 bucket:

echo "hello world" > /tmp/hello-world

aws s3 cp /tmp/hello-world s3://test/hello-world --profile localstack --endpoint-url=http://localhost:4566

  1. You should see a hello-world file in your local S3 bucket.

aws s3 ls s3://test/ --profile localstack --endpoint-url=http://localhost:4566

LocalStack AWS CDK solution overview

Using LocalStack, you can build and test your infrastructure-as-code configurations such as AWS CDK and AWS CloudFormation locally. LocalStack makes this possible using a custom wrapper, such as cdklocal, where all the AWS calls are redirected to the running LocalStack container. With this approach, CDK constructs can be rapidly tested on LocalStack with minimal modifications before deployment to AWS environments, thus making the process agile and reducing cost.

Solution walkthrough: Implementing Well-Architected Best Practices for Amazon SQS with CDK

In this example, we set up an inventory management system using Amazon S3, AWS Lambda,  Amazon SQS, and Amazon DynamoDB. CSV files are uploaded to the S3 bucket, which triggers a Lambda function to read and parse the CSV file. Each record is transformed into a message and sent to an SQS queue. A Lambda function polls the SQS queue for new messages and further updates the inventory levels in DynamoDB accordingly. Here is a step-by-step guide on how to deploy a Python CDK project to accomplish this task on your local machine using LocalStack.

Architecture diagram of the inventory management system we are deploying using CDK

Clone the code repository and install dependencies

The code for the solution in this post is in this repository on GitHub. Clone the AWS Samples repository that contains the AWS CDK project and other associated files.

  1. Use git clone to clone the repository onto your local developer machine:

git clone https://github.com/aws-samples/amazon-sqs-best-practices-cdk.git

  1. Install the cdklocal – cdklocal is a wrapper over the AWS CDK library and is available as an npm package. Use the following command to install it:

npm install -g aws-cdk-local aws-cdk

Note: Depending on your local setup, you might not have to use the global npm installation flag -g in the preceding code. You might also need administrator permissions to install the packages.

Start LocalStack and set up AWS CDK configuration

Make sure that the Docker daemon is running locally. This is generally done by starting the Docker Desktop application.

  1. Start LocalStack on your machine by running the following command:

localstack start -d

  1. You can create a Python virtual environment using virtualenv with the following command:

python3 -m venv .venv

  1. After initializing the virtual environment, activate it using the following command:

source .venv/bin/activate

Deploy the AWS CDK project locally

Now that your code is in place, you can deploy your project locally using LocalStack.

  1. Install the required AWS CDK dependencies in your local directory using pip. Please make sure that you are in the root directory of the repository you cloned:

pip install -r requirements.txt

  1. Bootstrap your local AWS environment for AWS CDK by running the following command:

cdklocal bootstrap

You will notice that we’re using the cdklocal package instead of cdk. Under the hood, cdklocal is wrapping the cdk package to redirect all the AWS API calls to the running LocalStack container.

  1. Deploy the AWS CDK project on your LocalStack container:

cdklocal deploy

You can review the AWS Identity and Access Management (IAM) policies that will be created locally, and enter y to continue when prompted.

After your project finishes deploying, review the local AWS resources that have been created.

Test the AWS CDK project locally

Using standard AWS CLI commands, you can test your newly created AWS CDK stack locally.

  1. Retrieve the name of the local S3 bucket we created using the following command:

BUCKET_NAME=$(aws s3 ls --profile localstack --endpoint-url=http://localhost:4566 | grep sqsblogstack-inventoryupdatesbucketfe | awk '{print $3}')

  1. You can copy the csv file in the sqs_blog directory to the local S3 bucket we created using the following command.

aws s3 cp --profile localstack --endpoint-url=http://localhost:4566 sqs_blog/sample_file.csv s3://$BUCKET_NAME

  1. You may now see the inventory updates in the DynamoDB table. Run the following commands to scan the table using AWS CLI:

TABLE_NAME=$(aws dynamodb --profile localstack --endpoint-url=http://localhost:4566  list-tables | grep -o '"SqsBlogStack-[^"]*' | awk -F '"' '{print $2}')

aws dynamodb scan --profile localstack --endpoint-url=http://localhost:4566  --table-name "$TABLE_NAME"

Consider these security best practices when using LocalStack. Mock credentials should be used with integrations like AWS CLI and CDK. It helps to maintain a clear separation between your actual AWS environment and LocalStack. We recommend using the LocalStack offline images for air-gapped environments without internet access. Auth tokens should never be stored in public repositories. If a token is exposed, immediately rotate the key to prevent access with the compromised credentials.

Cleanup

After you’re finished, delete the resources you created. This can be done by stopping the LocalStack container manually or by running the following command:

localstack stop

LocalStack is ephemeral, causing any local AWS resources generated within it to be automatically deleted when the container stops. However, there are methods to retain AWS resources. One approach is to enable persistence by setting PERSISTENCE=1 when starting LocalStack. Alternatively, you can develop a Cloud Pod that can be shared with your team members and injected into a currently running LocalStack container, allowing the resources to be preserved and accessible beyond the container’s lifecycle.

How to Launch LocalStack Cloud Emulator from AWS Marketplace

You saw how to emulate LocalStack locally and if you would like leverage the Pro version of LocalStack which support additional APIs and advanced features, you may easily procure the license from AWS Marketplace by following the instructions below:

Sign in to the AWS Management Console and go to the AWS Marketplace console. Enter LocalStack Cloud Emulator in the search field and choose Team Plan.

The LocalStack Team tier includes LocalStack Cloud Emulator and:

  • Access to all the locally emulated AWS services provided by LocalStack with best-effort support.
  • LocalStack in CI to test your cloud applications and infrastructure on your CI pipelines.
  • Stack Insights for a detailed audit log of your app’s interactions and API error codes over time.
  • Cloud Pods for taking persistent snapshots of your LocalStack instance and enabling collaborative debugging.

With the LocalStack Cloud Emulator from AWS Marketplace, developer teams have the flexibility to use their allocated budget for AWS while using LocalStack’s core emulation features.

Conclusion

In this post, we demonstrated how you can use LocalStack on your developer machine to test your AWS CDK projects locally. You can use LocalStack’s integrations to further test your project in different configurations, and use a wide range of AWS services, LocalStack tooling, language SDKs, and application development frameworks. LocalStack helps you build solutions in a way that’s nimble, optimizes cost, reduces contention, and delivers resilient and secure value to your customers.

By harnessing the power of LocalStack, businesses can significantly accelerate processes, minimizing their reliance on long-running dev and test loops. This results in a streamlined approach that combines various development and test environments, fostering greater efficiency and yielding notable cost advantages. Embracing LocalStack is integral to a test-driven development approach characterized by high velocity and superior quality, thereby empowering organizations to remain nimble and adaptable in their innovation journey.

About Authors

Sarath Krishnan

Sarath Krishnan is a Senior Solutions Architect with Amazon Web Services. He is passionate about enabling enterprise customers on their digital transformation journey. Sarath has extensive experience in architecting highly available, scalable, cost effective and resilient applications on the Cloud. His area of focus includes DevOps, Machine Learning, MLOps and Generative AI.

Waldemar Hummer

Waldemar Hummer is co-founder and CTO of LocalStack, where he and his team are building the world-leading platform for local cloud development! Prior to founding LocalStack, Waldemar has held several engineering and management roles at startups as well as large international companies, including Atlassian, IBM, and Zurich Insurance.

Harsh Mishra

Harsh Mishra is an Engineer at LocalStack and AWS Community Builder. Harsh has previously worked at HackerRank, Red Hat, and Quansight, and specialized in DevOps, Platform Engineering, and CI/CD pipelines.