How we made Step Functions call any AWS service locally

#stepfunctions #devops #cicd #aws

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" } }
  }
}

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

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

How it works

The dispatcher:

Parses the ARN to extract service name and action
Looks up the service in MiniStack's handler map
Constructs the right headers (X-Amz-Target for JSON services)
Converts PascalCase keys to the format each service expects
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

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",
)