Using Localstack

index.md

Using Localstack

Localstack is a framework for testing AWS services.

These are some nuggets I've collected while working with Localstack.

Installing Localstack

pip install localstack

Docker Engine Needs to Be Running to Start Localstack

I start up Docker Desktop prior to running localstack start. This starts the Docker Engine. Once I have that running, I can then start Localstack, which creates and runs a Docker container.

Run localstack start To Start Localstack

localstack start

You Can Also Run Docker-Compose Up To Start Localstack

docker-compose up

Not too familiar with the Docker CLI, but localstack start/docker-compose up apparently runs this command under the hood:

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

Localstack Serves “Edge Services” From Port 4566

Localstack serves from port 4566 by default. You can set the edge port in a few different ways.

You Can Change the Edge Port Using the EDGE_PORT Environment Variable

EDGE_PORT=9999 localstack start

While running localstack, making a request to http://localhost:4566 returns:

{
  "status": "running"
}

An example docker-compose.yaml file

You can find many examples of docker-compose.yaml files that use Localstack in Localstack issues. Here is one below.

version: "3.8"

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME-localstack_main}"
    image: localstack/localstack
    networks:
        - localstack-network
    ports:
      - "4566:4566"
      - "127.0.0.1:${PORT_WEB_UI-8080}:${PORT_WEB_UI-8080}"
    environment:
      - SERVICES=dynamodb,iam,sts
      - DEBUG=0
      - DEFAULT_REGION=us-east-1
      - AWS_DEFAULT_REGION=us-east-1
      - DATA_DIR=${DATA_DIR- }
      - PORT_WEB_UI=${PORT_WEB_UI- }
      - LAMBDA_EXECUTOR=${LAMBDA_EXECUTOR- }
      - KINESIS_ERROR_PROBABILITY=${KINESIS_ERROR_PROBABILITY- }
      - DOCKER_HOST=unix:///var/run/docker.sock
      - HOST_TMP_FOLDER=${TMPDIR}
      - LOCALSTACK_API_KEY=xxxxxx
      - ENFORCE_IAM=1
      - REQUESTS_CA_BUNDLE=
      - CA_BUNDLE=
      - AWS_CA_BUNDLE=
    volumes:
      - "${TMPDIR:-/tmp/localstack}:/tmp/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

  aws-cli:
    build:
      context:  ./
      dockerfile: Dockerfile
    environment:
    - AWS_ACCESS_KEY_ID=test
    - AWS_SECRET_ACCESS_KEY=test
    - AWS_DEFAULT_REGION=us-east-1
    volumes:
        - ./files:/files
    restart: on-failure
    networks:
        - localstack-network
    depends_on:
      - localstack

networks:
    localstack-network:
        name: localstack-network
        driver: bridge

Localstack Only Supports a Subset of AWS Services

Below are the services that Localstack supports for free:

• ACM (AWS Certificate Manager)
• API Gateway
• CloudFormation
• CloudWatch
• CloudWatch Logs
• DynamoDB
• DynamoDB Streams
• EC2 (Elastic Compute Cloud)
• Elasticsearch Service
• EventBridge (CloudWatch Events)
• Firehose
• IAM (Identity & Access Management)
• Kinesis
• KMS (Key Management Service)
• Lambda
• Redshift
• Route53
• S3 (Simple Storage Service)
• SecretsManager
• SES (Simple Email Service)
• SNS (Simple Notification Service)
• SQS (Simple Queue Service)
• SSM (Systems Manager)
• StepFunctions
• STS (Security Token Service)

Some Services Are Only Supported on a Premium Localstack Account

• Amplify
• API Gateway V2 (WebSockets support)
• Application AutoScaling
• AppSync
• Athena
• Backup
• Batch
• CloudFront
• CloudTrail
• Cognito
• CostExplorer
• DocumentDB
• ECS/ECR/EKS
• ElastiCache
• ElasticBeanstalk
• ELB/ELBv2
• EMR
• Glacier / S3 Select
• IAM Security Policy Enforcement
• IoT
• Kinesis Data Analytics
• Lambda Layers & Container Images
• Managed Streaming for Kafka (MSK)
• MediaStore
• Neptune Graph DB
• QLDB
• RDS / Aurora Serverless
• Timestream
• Transfer
• XRay

Localstack Can Be Integrated With the Serverless Framework

See: https://localstack.cloud/docs/how-to/serverless/

aws-local Can Be Used as a Thin CLI Wrapper to Shorten CLI Localstack Calls

To install aws-local:

pip install awscli-local

With aws-local, instead of calling:

ws --endpoint-url=http://localhost:4566 secretsmanager list-secrets

You can do:

awslocal secretsmanager list-secrets