using-localstack
npx machina-cli add skill SpillwaveSolutions/using-localstack-plugin/using-localstack --openclawMastering 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
-
Install:
pipx install localstack(recommended: isolated Python env, cross-platform) ORbrew install localstack/tap/localstack-cli(macOS-only, simpler on M1/M2) -
Start:
- Community:
localstack start -d - Pro:
LOCALSTACK_AUTH_TOKEN=<token> localstack start -d --version x.y.z
- Community:
-
Health check:
curl http://localhost:4566/_localstack/health | jq
Verify: All needed services show"available"or"running" -
CLI: Use
awslocal <service> ...(wrapper for AWS CLI with endpoint preset to localhost:4566)
Verify:awslocal sts get-caller-identity(should return any identity without error) -
S3 smoke:
awslocal s3 mb s3://demo && awslocal s3 ls
Verify: Output includesdemobucket; if not, check logs:docker logs localstack | grep -i s3 -
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.TableStatusreturns"ACTIVE"
Debug: If fails, check service health:curl http://localhost:4566/_localstack/health | jq .services.dynamodb -
Lambda smoke: Package code,
awslocal lambda create-function ..., theninvoke
Verify: Check invocation result and CloudWatch logs:awslocal logs tail /aws/lambda/<function-name> -
Events: Create SQS queue/SNS topic/EventBridge rule; wire S3/Lambda triggers; push test event
See Service Workflows for detailed event-driven patterns -
IaC: Use
tflocal/cdklocal/CloudFormation against LocalStack
See IaC Deployment for toolchain setup and patterns -
Observe:
docker logs localstack,LS_LOG=tracefor deep traces
See Debugging & Observability for troubleshooting
Architecture Concepts
- Single edge port (4566) routes all service APIs; use
*.localhost.localstack.cloudfor 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 - Installation, runtime tuning, persistence, ports, resource allocation
- Service Workflows - S3, Lambda, DynamoDB, EventBridge, MSK, EKS, RDS, Step Functions, CloudWatch
- Docker-Based Lambda & Fargate - Container images, ECR, Lambda packaging, Fargate orchestration, networking
- Docker Desktop Troubleshooting - Diagnostic flowchart for networking, compute, persistence, IAM, and performance issues
- Rancher Desktop Troubleshooting - Lima/WSL2 virtualization, containerd vs Moby, socket interfaces, VZ/VirtioFS optimization
- IaC Deployment - Terraform, CDK, CloudFormation patterns and toolchain setup
- State & Seeding - Persistence, Cloud Pods, init hooks, parallel environments
- Debugging & Observability - Logs, health checks, failure injection, networking
- CI/CD Patterns - Container-based integration testing
- Sharp Edges - Limits, gotchas, AWS parity gaps
Examples & Scripts
- End-to-End Examples - Complete workflows, helper scripts, integration tests
- docker-compose.yml - Production-grade LocalStack configuration
- e2e-lambda-fargate-s3.sh - Full Lambda + Fargate + S3 workflow
- 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
git clone https://github.com/SpillwaveSolutions/using-localstack-plugin/blob/main/plugins/using-localstack-plugin/skills/using-localstack/SKILL.mdView on GitHub Overview
Mastering LocalStack Pro teaches you to emulate AWS locally with high fidelity for production-parity workflows. It covers setup, deployment, management, monitoring, and sharp-edge guidance to debug IAM, networking, and event flows offline, enabling fast, deterministic testing of complex stacks.
How This Skill Works
LocalStack runs AWS service emulations on localhost and exposes a single edge port (4566). You interact via awslocal and IaC toolchains (tflocal, cdklocal, CloudFormation) to deploy and test stacks. Pro adds fidelity for advanced services (MSK/Kinesis+Pipes, EKS/ECS/Fargate, Aurora/RDS, Step Functions) and observability features to mirror production.
When to Use It
- Stand up AWS stacks locally (S3, Lambda, DynamoDB, API Gateway, EventBridge, MSK, EKS, RDS/Aurora, Step Functions).
- Build deterministic CI/CD pipelines without hitting real AWS.
- Debug IAM, networking, events, or data flows offline before deployment to AWS.
- Prototype high-fidelity stacks (EKS/MSK/Aurora/Step Functions) for production-like testing.
- Validate IaC toolchains (tflocal, cdklocal, CloudFormation) against LocalStack before cloud deployment.
Quick Start
- Step 1: Install LocalStack (pipx install localstack) or (brew install localstack/tap/localstack-cli).
- Step 2: Start LocalStack (Community: localstack start -d; Pro: LOCALSTACK_AUTH_TOKEN=<token> localstack start -d --version x.y.z).
- Step 3: Health check and smoke tests (curl http://localhost:4566/_localstack/health | jq; awslocal s3 mb s3://demo && awslocal s3 ls).
Best Practices
- Install LocalStack in an isolated environment (pipx) or via Homebrew; keep versions aligned with your project.
- Use awslocal for all CLI calls, targeting localhost:4566, and perform regular health checks.
- Start with Community for basic tests; upgrade to Pro for MSK/Kinesis, EKS/ECS/Fargate, and Step Functions fidelity when needed.
- Enable deep tracing with LS_LOG=trace and monitor docker logs for issues during debugging.
- Validate infrastructure as code with tflocal/cdklocal/CFN to ensure repeatable, offline-ready deployments.
Example Use Cases
- Build a local data pipeline using S3, Lambda, and DynamoDB to validate event-driven processing offline.
- Run a deterministic CI/CD pipeline against LocalStack to test deploy workflows before AWS.
- Debug IAM policies and networking rules in a sandboxed environment without affecting production.
- Prototype an EKS-based microservice stack alongside MSK streaming for production-like tests.
- Simulate end-to-end event flows (S3 -> Lambda -> SNS/SQS -> EventBridge) with observability in place.
