Step Functions (LocalStack)

This guide shows you how to work with AWS Step Functions locally using LocalStack, Python, and VS Code AWS Toolkit. This lab demonstrates a user onboarding workflow with parallel Lambda execution and IAM user creation.

Prerequisites

Docker installed and running.
Dev Containers extension installed (optional).
AWS Toolkit for VS Code (included in Dev Container).
AWS CLI (included in Dev Container).

How to execute

Setup Environment:
- Dev Container (recommended)
- Manually
Open VS Code in the project folder and execute this command in the Command Palette:
Terminal window
> Dev Containers: Reopen in Container
Terminal window
pip3 install uv && uv sync

Configure LocalStack Profile: Set up a dedicated AWS profile for LocalStack:

aws configure set aws_access_key_id test --profile localstack
aws configure set aws_secret_access_key test --profile localstack
aws configure set region us-east-1 --profile localstack
aws configure set output json --profile localstack
aws configure set endpoint_url http://localhost:4566 --profile localstack

Run the Example:
- Start LocalStack:
  Terminal window
```
docker compose up -d
```
- Deploy infrastructure:
  Terminal window
```
python deploy.py
```
- Run the workflow:
  Terminal window
```
python main.py
```

Working with AWS Toolkit

Open Command Palette: Press F1 or Ctrl+Shift+P.
Connect to AWS: Type and select AWS: Connect to AWS.
Select Profile: Select the localstack profile.
Render Graph: Open step_function.asl.json and click the Visual Graph icon (top-right).
Execute: In the AWS Explorer, right-click UserOnboardingWorkflow and select Start Execution.

Validate results

Verify IAM User Creation:
Terminal window
```
aws iam list-users --profile localstack
```

Verify DynamoDB Logs:

aws dynamodb scan --table-name UserLogs --profile localstack

Verify Lambda Functions:

aws lambda list-functions --profile localstack

Clean Up

docker compose down -v

Troubleshooting

Issue	Solution
Lambda function is ‘Pending’	Wait 5-10 seconds after `deploy.py` and try again. LocalStack may still be initializing the Lambda environment.
Connection refused	Ensure LocalStack is running: `docker ps`