serverless-step-functions-local

Run AWS step functions offline with Serverless!

This is a plugin for the Serverless Framework. It uses stepfunctions-localhost to emulate step functions with AWS' provided tool for local development.

Requirements

• serverless >= v3.0.0
• The serverless-offline plugin
• The serverless-offline-lambda plugin
• The serverless-step-functions plugin
• Java Runtime Engine (JRE) version 6.x or newer

Install

npm install serverless-step-functions-local -D

Getting Started

You'll need to add this plugin to your serverless.yml. The plugins section should look something like this when you're done:

1plugins:
2  ...
3  - serverless-step-functions
4  - serverless-step-functions-local
5  - serverless-offline-lambda
6  - serverless-offline
7  ...

Then, add a new section to config with accountId and region parameters:

1custom:
2  stepFunctionsLocal:
3    accountId: 101010101010
4    region: us-east-1

Although not neccessary, it's strongly recomended to add the folder with the downloaded step function executables to .gitignore. By default, this path is ./.step-functions-local.

The plugin binds to port 8083, this cannot be changed. The plugin binds to port 8083, since stepfunctions-localhost doesn't support dynamic port, it can't be changed.

It also adds an environment variable for each created state machine that contains the ARN for it. These variables are prefixed by OFFLINE_STEP_FUNCTIONS_ARN_, so the ARN of a state machine named 'WaitMachine', for example could be fetched by reading OFFLINE_STEP_FUNCTIONS_ARN_WaitMachine.

Options

(These go under custom.stepFunctionsLocal.)

• accountId (required) your AWS account ID
• region (required) your AWS region
• lambdaEndpoint (defaults to http://localhost:3000 from serverless offline) the endpoint for the lambda service. This plugin tries to use the configured value from serverless-offline
• path (defaults to ./.step-functions-local) the path to store the downloaded step function executables
• TaskResourceMapping allows for Resource ARNs to be configured differently for local development. (Serverless 3.x prefixes the lambda function names with the stack name and the stage)
• eventBridgeEvents allows sending EventBridge events on execution status changes
  • enabled (bool) enabled or disable this feature. Disabled by default.
  • endpoint Endpoint for sending events to eg. for serverless-offline-aws-eventbridge would be http://localhost:4010
• externalInstance allows to set a flag to use external instance of local step functions. Disabled by default.
• stepFunctionsEndpoint (defaults to http://localhost:8083) the endpoint for the step functions service

Full Config Example

1service: local-step-function
2
3plugins:
4  - serverless-step-functions
5  - serverless-step-functions-local
6  - serverless-offline-lambda
7  - serverless-offline
8
9provider:
10  name: aws
11  runtime: nodejs14.x # supported nodejs versions: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html
12
13
14custom:
15  stepFunctionsLocal:
16    accountId: 101010101010
17    region: us-east-1
18    TaskResourceMapping:
19      FirstState: arn:aws:lambda:us-east-1:101010101010:function:${self:service}-${opt:stage, self:provider.stage}-hello
20      FinalState: arn:aws:lambda:us-east-1:101010101010:function:${self:service}-${opt:stage, self:provider.stage}-hello
21    eventBridgeEvents:
22      enabled: true
23      endpoint: http://localhost:4010
24  sqsUrl: http://localhost:4566/101010101010/example-queue
25
26functions:
27  hello:
28    handler: handler.hello
29
30stepFunctions:
31  stateMachines:
32    WaitMachine:
33      definition:
34        Comment: "An example of the Amazon States Language using wait states"
35        StartAt: FirstState
36        States:
37          FirstState:
38            Type: Task
39            Resource: Fn::GetAtt: [hello, Arn]
40            Next: send_message
41          send_message:
42            Type: Task
43            Resource: arn:aws:states:::sqs:sendMessage
44            Parameters:
45              QueueUrl: ${self:custom.sqsUrl}
46              "MessageBody.$": "$"
47            Next: wait_using_seconds
48          wait_using_seconds:
49            Type: Wait
50            Seconds: 10
51            Next: FinalState
52          FinalState:
53            Type: Task
54            Resource: Fn::GetAtt: [hello, Arn]
55            End: true

Start your local step functions

To run your local step function, use this command:

aws stepfunctions --endpoint-url http://localhost:8083 start-execution --state-machine-arn arn:aws:states:us-east-1:101010101010:stateMachine:servicename-stagename-hello --input '{"hello": ["world"]}'

Running external instance

To run external step functions local using docker, use this command:

docker run \
    -p 8083:8083 \
    -e "AWS_ACCOUNT_ID=101010101010" \
    -e "AWS_DEFAULT_REGION=us-east-1" \
    -e "LAMBDA_ENDPOINT=http://localhost:4000" \
    amazon/aws-stepfunctions-local