Using Localstack

Mastering LocalStack Pro — Practitioner Skill

Operations-first playbook to emulate AWS locally with high fidelity. Focuses on production-parity workflows (event-driven, streaming, containers, IaC), fast debugging, and deterministic CI.

Audience & Outcomes

• For senior backend/platform/DevOps/AI-data engineers needing production-parity local AWS for event-driven, streaming, and data/agentic workloads
• Assumes AWS fluency; focuses on emulator fidelity vs AWS deltas
• Outcomes: spin up complex stacks locally (EKS/MSK/Aurora/Step Functions), debug IAM/networking/event flows, run deterministic CI/CD

When to Use

• Stand up AWS stacks locally (S3, Lambda, DynamoDB, API Gateway, EventBridge, MSK, EKS, RDS/Aurora, Step Functions)
• Build deterministic CI/CD without hitting real AWS
• Debug IAM, networking, events, or data flows offline before deploying to AWS

When Not to Use

• Production deployments (LocalStack is for dev/test only)
• Multi-region/global table testing (single-region emulation)
• Performance/scale validation (no multi-AZ, different latency profile)
• Managed service edge cases (simplified IAM enforcement, custom resources may differ)

Community vs Pro

• Community: core services (S3, basic Dynamo, Lambda, API GW) for simple serverless
• Pro: advanced services and fidelity (MSK/Kinesis+Pipes, EKS/ECS/Fargate, Aurora/RDS, Step Functions with mocking/visualization, EventBridge schema/pipes, IAM enforcement/Policy Stream, Cloud Pods, offline bundles)

Use Pro when avoiding deploy-to-test cycles outweighs license cost.

Quick Start

1. Install: pipx install localstack (recommended: isolated Python env, cross-platform) OR brew install localstack/tap/localstack-cli (macOS-only, simpler on M1/M2)

1. Start:

• Community: localstack start -d
• Pro: LOCALSTACK_AUTH_TOKEN= localstack start -d --version x.y.z

1. Health check: curl http://localhost:4566/_localstack/health | jq

Verify: All needed services show "available" or "running"

1. CLI: Use awslocal ... (wrapper for AWS CLI with endpoint preset to localhost:4566)

Verify: awslocal sts get-caller-identity (should return any identity without error)

1. S3 smoke: awslocal s3 mb s3://demo && awslocal s3 ls

Verify: Output includes demo bucket; if not, check logs: docker logs localstack | grep -i s3

1. DynamoDB smoke: awslocal dynamodb create-table --table-name test --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST

Verify: awslocal dynamodb describe-table --table-name test | jq .Table.TableStatus returns "ACTIVE" Debug: If fails, check service health: curl http://localhost:4566/_localstack/health | jq .services.dynamodb

1. Lambda smoke: Package code, awslocal lambda create-function ..., then invoke

Verify: Check invocation result and CloudWatch logs: awslocal logs tail /aws/lambda/

1. Events: Create SQS queue/SNS topic/EventBridge rule; wire S3/Lambda triggers; push test event

See [Service Workflows](references/services.md) for detailed event-driven patterns

1. IaC: Use tflocal/cdklocal/CloudFormation against LocalStack

See [IaC Deployment](references/iac.md) for toolchain setup and patterns

1. Observe: docker logs localstack, LS_LOG=trace for deep traces

See [Debugging & Observability](references/debugging.md) for troubleshooting

Architecture Concepts

• Single edge port (4566) routes all service APIs; use *.localhost.localstack.cloud for service hostnames
• Providers execute actual service logic (SNS→SQS fan-out, S3 event triggers) not stubs; scale/latency differs from AWS
• Event-first bus: cross-service notifications emitted internally; ideal for testing async S3/SNS/SQS/EventBridge/Lambda flows
• Hermetic by default: prefer endpoint injection/DNS over hardcoding localhost:4566; treat persistence as optional

Detailed Guides

• [Setup & Configuration](references/setup.md) - Installation, runtime tuning, persistence, ports, resource allocation
• [Service Workflows](references/services.md) - S3, Lambda, DynamoDB, EventBridge, MSK, EKS, RDS, Step Functions, CloudWatch
• [Docker-Based Lambda & Fargate](references/docker-lambda-fargate.md) - Container images, ECR, Lambda packaging, Fargate orchestration, networking
• [Docker Desktop Troubleshooting](references/docker-desktop-troubleshooting.md) - Diagnostic flowchart for networking, compute, persistence, IAM, and performance issues
• [Rancher Desktop Troubleshooting](references/rancher-desktop-troubleshooting.md) - Lima/WSL2 virtualization, containerd vs Moby, socket interfaces, VZ/VirtioFS optimization
• [IaC Deployment](references/iac.md) - Terraform, CDK, CloudFormation patterns and toolchain setup
• [State & Seeding](references/state.md) - Persistence, Cloud Pods, init hooks, parallel environments
• [Debugging & Observability](references/debugging.md) - Logs, health checks, failure injection, networking
• [CI/CD Patterns](references/ci-cd.md) - Container-based integration testing
• [Sharp Edges](references/sharp-edges.md) - Limits, gotchas, AWS parity gaps

Examples & Scripts

• [End-to-End Examples](examples/README.md) - Complete workflows, helper scripts, integration tests
• [docker-compose.yml](examples/docker-compose.yml) - Production-grade LocalStack configuration
• [e2e-lambda-fargate-s3.sh](examples/e2e-lambda-fargate-s3.sh) - Full Lambda + Fargate + S3 workflow
• [ecr-helper.sh](examples/ecr-helper.sh) - ECR repository and image management utility

Official References

• Overview: https://docs.localstack.cloud/overview/
• Installation: https://docs.localstack.cloud/getting-started/installation/
• Configuration: https://docs.localstack.cloud/references/configuration/
• Service guides: https://docs.localstack.cloud/aws/services/
• Step Functions testing/mocking: https://blog.localstack.cloud/aws-step-functions-mocking/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SpillwaveSolutions
• Source: SpillwaveSolutions/using-localstack-plugin
• License: MIT

Install and usage instructions live in the source repository linked above.