How we made Step Functions call any AWS service locally

How we made Step Functions call any AWS service locally

# stepfunctions# devops# cicd# aws
How we made Step Functions call any AWS service locallyNahuel Nucera

If you've used AWS Step Functions, you know the aws-sdk:* integration pattern: { "Type":...

If you've used AWS Step Functions, you know the aws-sdk:* integration pattern:

{
  "Type": "Task",
  "Resource": "arn:aws:states:::aws-sdk:dynamodb:PutItem",
  "Parameters": {
    "TableName": "my-table",
    "Item": { "pk": { "S.$": "$.id" } }
  }
}
Enter fullscreen mode Exit fullscreen mode

One line in your state machine, and Step Functions calls DynamoDB directly. No Lambda wrapper needed. AWS recommends this for all new workflows.

The problem? Every local AWS emulator hardcodes service integrations. Want SQS? There's a handler. Want SNS? Another handler. Want SecretsManager? Sorry, not implemented yet.

The generic dispatcher

We added a generic aws-sdk:* task dispatcher to MiniStack. Instead of writing a handler for each service, it routes to whatever service is already emulated:

arn:aws:states:::aws-sdk:secretsmanager:CreateSecret  → SecretsManager handler
arn:aws:states:::aws-sdk:dynamodb:PutItem              → DynamoDB handler  
arn:aws:states:::aws-sdk:ecs:RunTask                   → ECS handler
arn:aws:states:::aws-sdk:kms:Encrypt                   → KMS handler
Enter fullscreen mode Exit fullscreen mode

38 services. All callable from Step Functions. No new code needed per service.

How it works

The dispatcher:

  1. Parses the ARN to extract service name and action
  2. Looks up the service in MiniStack's handler map
  3. Constructs the right headers (X-Amz-Target for JSON services)
  4. Converts PascalCase keys to the format each service expects
  5. Calls the handler and returns the result to the workflow

For JSON-protocol services (DynamoDB, SecretsManager, ECS, KMS, CloudWatch Logs, SSM, EventBridge, Kinesis, Glue, Athena, ECR), it works today. Query and REST protocol services are coming.

What else ships with MiniStack

  • 38 AWS services on a single port
  • 1,047 integration tests
  • 48 CloudFormation resource types — CDK bootstrap + deploy works
  • Terraform VPC module v6.6.0 fully compatible
  • Lambda — Python, Node.js, Go/Rust/C++ (Docker), Docker images
  • Real infrastructure — RDS spins up Postgres, ElastiCache runs Redis, ECS starts Docker containers

Try it 

docker run -p 4566:4566 nahuelnucera/ministack
Enter fullscreen mode Exit fullscreen mode

Then run your Step Functions workflow locally:

import boto3

sfn = boto3.client("stepfunctions",
    endpoint_url="http://localhost:4566",
    region_name="us-east-1",
    aws_access_key_id="test",
    aws_secret_access_key="test")

# Your workflow can now call any of the 38 services
sfn.create_state_machine(
    name="my-workflow",
    definition='...your ASL with aws-sdk integrations...',
    roleArn="arn:aws:iam::000000000000:role/role",
)
Enter fullscreen mode Exit fullscreen mode

MIT licensed. Free forever. github.com/Nahuel990/ministack