Working with AWS on local using LocalStack

Developing with AWS comes with its own set of challenges. If your organization has strict policies on cloud resources, prototyping with the AWS services can become a hassle. LocalStack is a container-based technology which brings a comprehensive set of AWS services on your local machine. It plays well with the official AWS CLI and SDK. In this guide, I’ll talk about how to setup LocalStack and use it with the AWS CLI.

Setup

The examples in this post use

Docker Engine 20.10.17
AWS CLI 2.7.14

Configure a local AWS account

LocalStack works with a local AWS account which you can configure with the AWS CLI. Launch the aws configure command as follows.

sh
Configuring the AWS account

1aws configure
2AWS Access Key ID [None]: gwen
3AWS Secret Access Key [None]: stacy
4Default region name [None]: us-east-1
5Default output format [None]: json

You can put fake AWS Access Key ID and AWS Secret Access Key here. Although LocalStack requires an AWS account configured, it doesn’t validate them.

Launching the LocalStack container

Pull the latest LocalStack image from Docker.

docker pull localstack/localstack:latest

Create a Compose file as follows.

yaml
localstack.yml

 1version: '3'
 2
 3services:
 4  aws:
 5    image: localstack/localstack:latest
 6    environment:
 7      DEBUG: 1
 8      LAMBDA_DOCKER_NETWORK: my-local-aws-network
 9      LAMBDA_REMOTE_DOCKER: 0
10      SERVICES: s3,sqs,secretsmanager
11    ports:
12      - 4566:4566
13    volumes:
14      - /var/run/docker.sock:/var/run/docker.sock
15
16networks:
17  default:
18    name: my-local-aws-network

You can now launch the container with the following command.

docker compose -f localstack.yml up -d

Once the container is up and running, open a terminal and ping the healthcheck endpoint. If things are working, you would see the status of the available services as “available”.

sh
Healthcheck for LocalStack container

 1curl localhost:4566/health
 2{
 3  "features": {
 4    "initScripts": "initialized"
 5  },
 6  "services": {
 7    "apigateway": "available",
 8    "cloudformation": "available",
 9    "cloudwatch": "available",
10    "config": "available",
11    "dynamodb": "available",
12    "dynamodbstreams": "available",
13    "ec2": "available",
14    "es": "available",
15    "events": "available",
16    "firehose": "available",
17    "iam": "available",
18    "kinesis": "available",
19    "kms": "available",
20    "lambda": "available",
21    "logs": "available",
22    "opensearch": "available",
23    "redshift": "available",
24    "resource-groups": "available",
25    "resourcegroupstaggingapi": "available",
26    "route53": "available",
27    "route53resolver": "available",
28    "s3": "available",
29    "s3control": "available",
30    "secretsmanager": "available",
31    "ses": "available",
32    "sns": "available",
33    "sqs": "available",
34    "ssm": "available",
35    "stepfunctions": "available",
36    "sts": "available",
37    "support": "available",
38    "swf": "available"
39  },
40  "version": "1.0.0.dev"
41}

Working with AWS services

You can now use the AWS services (such as S3, SNS, SQS, Secrets Manager, etc) through the port 4566. You can find the list of the core AWS services available on LocalStack here. Let’s explore some services with AWS CLI now.

Saving objects on S3

Create a sample JSON file as follows, to save it on S3.

json
sample.json

 1{
 2	"name": "Madame Uppercut",
 3	"age": 39,
 4	"secretIdentity": "Jane Wilson",
 5	"powers": [
 6		"Million tonne punch",
 7		"Damage resistance",
 8		"Superhuman reflexes"
 9	]
10}

Let’s create a bucket, say my-bucket, as follows.

1aws --endpoint-url http://localhost:4566 s3api create-bucket --bucket my-bucket --region us-east-1
2{
3	"Location": "/my-bucket"
4}

You can list all the buckets with the following command.

 1aws --endpoint-url http://localhost:4566 s3api list-buckets
 2{
 3	"Buckets": [
 4		{
 5			"Name": "my-bucket",
 6			"CreationDate": "2022-07-12T13:44:44+00:00"
 7		}
 8	],
 9	"Owner": {
10		"DisplayName": "webfile",
11		"ID": "bcaf1ffd86f41161ca5fb16fd081034f"
12	}
13}

Now, you can upload the sample.json file on the new bucket.

1aws --endpoint-url http://localhost:4566 s3 cp sample.json s3://my-bucket/inner/sample.json --content-type 'application/json'
2upload: .\sample.json to s3://my-bucket/inner/sample.json

You can download the existing file from the S3 bucket as follows.

1aws --endpoint-url http://localhost:4566 s3 cp s3://my-bucket/inner/sample.json sample2.json --content-type 'application/json'
2download: s3://my-bucket/inner/sample.json to .\sample2.json

To delete the file, you can use the following command.

1aws --endpoint-url http://localhost:4566 s3 rm s3://my-bucket/inner/sample.json
2delete: s3://my-bucket/inner/sample.json

Finally, you can delete the bucket as follows.

aws --endpoint-url http://localhost:4566 s3api delete-bucket --bucket my-bucket

Refer to the s3 and s3api docs for more operations to try with LocalStack.

Publishing events with SQS

You can use the following command to create a queue called my-queue.

1aws --endpoint-url http://localhost:4566 sqs create-queue --queue-name my-queue
2{
3	"QueueUrl": "http://localhost:4566/000000000000/my-queue"
4}

To verify if the queue is available, list all the queues as follows.

1aws --endpoint-url http://localhost:4566 sqs list-queues
2{
3	"QueueUrls": [
4		"http://localhost:4566/000000000000/my-queue"
5	]
6}

Let’s publish a message using the send-message command.

1aws --endpoint-url http://localhost:4566 sqs send-message --queue-url http://localhost:4566/000000000000/my-queue --message-body "Gwen"
2{
3	"MD5OfMessageBody": "030997f386c4663f2c3e9594308c60b4",
4	"MessageId": "8c6257d2-84c8-4689-a6a1-1a37b1faa3ec"
5}

You can read the published messages through the receive-message command.

 1aws --endpoint-url http://localhost:4566 sqs receive-message --queue-url http://localhost:4566/000000000000/my-queue
 2{
 3	"Messages": [
 4		{
 5			"MessageId": "8c6257d2-84c8-4689-a6a1-1a37b1faa3ec",
 6			"ReceiptHandle": "ZDYzMmRjMmUtNWY2Yi00NzRmLWI1ZjQtYTYwNGJiZGRkMGFjIGFybjphd3M6c3FzOnVzLWVhc3QtMTowMDAwMDAwMDAwMDA6bXktcXVldWUgOGM2MjU3ZDItODRjOC00Njg5LWE2YTEtMWEzN2IxZmFhM2VjIDE2NTc2MzQwMDIuNzE3MDIyNA==",
 7			"MD5OfBody": "030997f386c4663f2c3e9594308c60b4",
 8			"Body": "Gwen"
 9		}
10	]
11}

Finally, to delete a message, you can use the delete-message command as follows. To delete the queue, use the delete-queue command.

1aws --endpoint-url http://localhost:4566 sqs delete-message --queue-url http://localhost:4566/000000000000/my-queue --receipt-handle ZDYzMmRjMmUtNWY2Yi00NzRmLWI1ZjQtYTYwNGJiZGRkMGFjIGFybjphd3M6c3FzOnVzLWVhc3QtMTowMDAwMDAwMDAwMDA6bXktcXVldWUgOGM2MjU3ZDItODRjOC00Njg5LWE2YTEtMWEzN2IxZmFhM2VjIDE2NTc2MzQwMDIuNzE3MDIyNA==
2
3aws --endpoint-url http://localhost:4566 sqs delete-queue --queue-url http://localhost:4566/000000000000/my-queue

For more operations, check the sqs docs.

Creating secrets with SecretsManager

To create a secret, you can use the create-secret command as follows.

1aws --endpoint-url http://localhost:4566 secretsmanager create-secret --name my-secret --secret-string '{"PG_PASSWORD":"stacy"}'
2{
3	"ARN": "arn:aws:secretsmanager:us-east-1:000000000000:secret:my-secret-b3dd81",
4	"Name": "my-secret",
5	"VersionId": "33395f3b-6f75-4c48-9424-33c730538063"
6}

You can also list all the secrets available on the Secrets Manager.

 1aws --endpoint-url http://localhost:4566 secretsmanager list-secrets
 2{
 3	"SecretList": [
 4		{
 5			"ARN": "arn:aws:secretsmanager:us-east-1:000000000000:secret:my-secret-b3dd81",
 6			"Name": "my-secret",
 7			"LastChangedDate": "2022-07-12T19:27:05.440032+05:30",
 8			"Tags": [],
 9			"SecretVersionsToStages": {
10				"33395f3b-6f75-4c48-9424-33c730538063": [
11					"AWSCURRENT"
12				]
13			},
14			"CreatedDate": "2022-07-12T19:27:05.440032+05:30"
15		}
16	]
17}

You can read the secrets with the get-secret-value command

 1aws --endpoint-url http://localhost:4566 secretsmanager get-secret-value --secret-id my-secret
 2{
 3	"ARN": "arn:aws:secretsmanager:us-east-1:000000000000:secret:my-secret-b3dd81",
 4	"Name": "my-secret",
 5	"VersionId": "33395f3b-6f75-4c48-9424-33c730538063",
 6	"SecretString": "{\"PG_PASSWORD\":\"stacy\"}",
 7	"VersionStages": [
 8		"AWSCURRENT"
 9	],
10	"CreatedDate": "2022-07-12T19:27:05.440032+05:30"
11}

Finally, you can delete a secret with its ARN.

1aws --endpoint-url http://localhost:4566 secretsmanager delete-secret --secret-id arn:aws:secretsmanager:us-east-1:000000000000:secret:my-secret-b3dd81
2{
3	"ARN": "arn:aws:secretsmanager:us-east-1:000000000000:secret:my-secret-b3dd81",
4	"Name": "my-secret",
5	"DeletionDate": "2022-08-11T19:29:39.904093+05:30"
6}

For more operations, check out the secretsmanager docs.

Conclusion

LocalStack is geared toward CLI and SDK driven workflows. If you need a desktop app, you can check out Commandeer, or LocalStack subscriptions which offer a Web UI.
Support for some AWS services (such as ElastiCache, ECS, EKS, etc) requires a subscription.

Source code

localstack-introduction

Weaving aspects at compile-time with AspectJ