LocalStack: Run AWS Services Locally

LocalStack is a free and open-source tool that allows you to run AWS services locally on your machine.

LocalStack is a free and open-source tool that allows you to run AWS services locally on your machine, enabling you to develop and test your cloud applications without having to connect to the real AWS cloud. This is accomplished by emulating AWS APIs and providing you a local interface to interact with these APIs.

LocalStack API

The LocalStack API is a RESTful API that mimics the AWS API. This means that you can use the same tools and libraries that you use to test your applications against the real AWS cloud to test your applications against LocalStack.

LocalStack allows you to emulate different services like Lambda, SQS, SNS or EC2, and also provides different levels of access to these APIs. You can check their feature coverage page here to understand the level of parity to the real AWS API and the pricing tier under which these APIs are available in LocalStack.

Benefits of Using LocalStack

LocalStack is a great way to:

• Speed up your development process
• Reduce costs
• Test your application and improve reliability

Why and When Should You Use LocalStack?

There are many reasons why you might want to use LocalStack. Here are a few of the most common:

• To speed up your development process. When you’re developing a cloud application, you often need to make changes to your code and then deploy those changes to the AWS cloud. This can be a time-consuming process, especially if you’re making a lot of changes. LocalStack allows you to test your changes locally, which can save you a lot of time.
• To reduce costs. If you’re developing a cloud application, you’ll need to pay for AWS resources like EC2 instances and S3 buckets. If you can test your application locally, you can reduce your AWS costs significantly.
• To improve reliability. When you deploy your application in the real AWS cloud, you have the peace of mind of having performed integration tests in addition to unit tests and other software tests. LocalStack allows you to test your application in a more isolated environment, using the same AWS APIs you would use once deployed to AWS, which can help you to improve the reliability of your application by finding errors while developing it, rather than after deploying it. It’s always cheaper to fix bugs or change your architecture in development rather than in production!

How to Install LocalStack

There are three ways to install LocalStack:

1. Using Homebrew (MacOS)

brew install localstack

2. Using the Installer

You can download the LocalStack installer from the LocalStack website. Once you’ve downloaded the installer, run it to install LocalStack.

3. Using Docker

LocalStack runs inside a Docker container. To start the LocalStack container, run:

docker run -it -p 4566:4566 localstack/localstack

How to Use LocalStack

Once you’ve installed LocalStack, you can start using it to test your cloud applications. To start LocalStack, run:

localstack start

Examples of Testing an AWS Service Locally

Here are a few examples of how you can use LocalStack to test an AWS service locally:

Testing an S3 Bucket

• Create a file in your local directory and upload it to an S3 bucket in LocalStack.
• Download the file from the S3 bucket and verify that it’s the same file that you uploaded.

Testing an SQS Queue

• Send a message to the queue and then receive the message from the queue.
• Verify that the message received is the same message that was sent.

Testing a Lambda Function

• Invoke the function and verify that it returns the expected result.

Using LocalStack with Python and AWS SDK (Boto3)

The following example demonstrates how to create an Amazon Simple Notification Service (SNS) topic and subscription using LocalStack and Boto3.

import boto3
from botocore.exceptions import ClientError
import logging
import sys

logging.basicConfig(
    stream=sys.stdout,
    level=logging.INFO,
    format="[%(levelname)s] %(asctime)s: %(message)s",
)
logger = logging.getLogger()

RUN_LOCAL = True
SNS_EMAIL_ENDPOINT = "test@email.com"  # Add email address to send notifications to.

# Setup Localstack Endpoint
endpoint_url = "http://localhost.localstack.cloud:4566"

def create_boto3_client_session(service_name: str, run_local=RUN_LOCAL):
    """Creates a boto3 client session for the specified service."""
    if run_local:
        logger.info(f"Creating boto3 client for {service_name} in localstack")
        return boto3.client(service_name, endpoint_url=endpoint_url)
    else:
        logger.info(f"Creating boto3 client for {service_name} in AWS")
        return boto3.client(service_name)

def create_sns_topic(name: str):
    """Create an SNS topic."""
    sns_client = create_boto3_client_session(service_name="sns")
    try:
        topic = sns_client.create_topic(Name=name)
        logger.info(f"Created SNS topic {topic}")
        return topic
    except ClientError:
        logger.exception("Failed to create SNS topic")
        raise

def create_sns_subscription(topic_arn: str, endpoint: str):
    """Create an SNS subscription."""
    sns_client = create_boto3_client_session(service_name="sns")
    try:
        subscription = sns_client.subscribe(
            TopicArn=topic_arn, Protocol="email", Endpoint=endpoint
        )
        logger.info(f"Created SNS subscription {subscription}")
        return subscription
    except ClientError:
        logger.exception("Failed to create SNS subscription")
        raise

if __name__ == "__main__":
    sns_topic = create_sns_topic(name="MyTestSNSTopic")
    sns_subscription = create_sns_subscription(
        topic_arn=sns_topic["TopicArn"], endpoint=SNS_EMAIL_ENDPOINT
    )

This script demonstrates how to:

• Create an SNS topic
• Create an email subscription for the topic
• Use a configurable flag (RUN_LOCAL) to switch between LocalStack and AWS

Code Walkthrough

After importing the required modules and setting up logging, I decided to have a flag to signal my script whether I want to run the script locally using LocalStack or against the real AWS APIs.

RUN_LOCAL = True

After I’m done testing, I can flip the flag to False and deploy the the application to AWS.

Next step is to store the LocalStack endpoint in a variable to tell our application how to connect to the emulated AWS APIs:

endpoint_url = "[http://localhost.localstack.cloud:4566](http://localhost.localstack.cloud:4566)"

When we create instances of AWS services using the SDK, first thing we need to do is to create a client session. If you are composing an application that creates multiple services, you have to create a client session for each service. This creates repetition of code as we instantiate multiple clients. Following the DRY principle, I’ve created the function create_boto3_client_session that takes two arguments, the service that we want to create a session for and whether to run locally or not, returning a client session for service passed onto it.

I then create two functions to create the SNS topic create_sns_topic and create subscription to the topic create_sns_subscription based on a passed email address as a subscription endpoint I’ve stored as global variable SNS_EMAIL_ENDPOINT. Finally, I call these two functions to create the SNS topic and subscription

Conclusion

LocalStack is a powerful tool that can help you speed up your development process, reduce costs, improve reliability, and test your applications in an isolated local environment. If you’re developing a cloud application, I highly recommend checking out LocalStack.

For more information, visit the LocalStack website.

• ← Previous Post