AWS Lambda Tasks - Amazon Simple Workflow Service

AWS Lambda Tasks

About AWS Lambda

AWS Lambda is a fully managed compute service that runs your code in response to events generated by custom code or from various AWS services such as Amazon S3, DynamoDB, Amazon Kinesis, Amazon SNS, and Amazon Cognito. For more information about Lambda, see the AWS Lambda Developer Guide.

Amazon Simple Workflow Service provides a Lambda task so that you can run Lambda functions in place of, or alongside traditional Amazon SWF activities.

Important

Your AWS account will be charged for Lambda executions (requests) executed by Amazon SWF on your behalf. For details about Lambda pricing, see https://aws.amazon.com/lambda/pricing/.

Benefits and limitations of using Lambda tasks

There are a number of benefits of using Lambda tasks in place of a traditional Amazon SWF activity:

  • Lambda tasks don’t need to be registered or versioned like Amazon SWF activity types.

  • You can use any existing Lambda functions that you've already defined in your workflows.

  • Lambda functions are called directly by Amazon SWF; there is no need for you to implement a worker program to execute them as you must do with traditional activities.

  • Lambda provides you with metrics and logs for tracking and analyzing your function executions.

There are also a number of limitations regarding Lambda tasks that you should be aware of:

  • Lambda tasks can only be run in AWS regions that provide support for Lambda. See Lambda Regions and Endpoints in the Amazon Web Services General Reference for details about the currently-supported regions for Lambda.

  • Lambda tasks are currently supported only by the base SWF HTTP API and in the AWS Flow Framework for Java. There is currently no support for Lambda tasks in the AWS Flow Framework for Ruby.

Using Lambda tasks in your workflows

To use Lambda tasks in your Amazon SWF workflows, you will need to:

  1. Set up IAM roles to provide Amazon SWF with permission to invoke Lambda functions.

  2. Attach the IAM roles to your workflows.

  3. Call your Lambda function during a workflow execution.

Set up an IAM role

Before you can invoke Lambda functions from Amazon SWF you must provide an IAM role that provides access to Lambda from Amazon SWF. You can either:

  • choose a pre-defined role, AWSLambdaRole, to give your workflows permission to invoke any Lambda function associated with your account.

  • define your own policy and associated role to give workflows permission to invoke particular Lambda functions, specified by their Amazon Resource Names (ARNs).

Limit permissions on an IAM role

You can limit permissions on an IAM role you provide to Amazon SWF by using the SourceArn and SourceAccount context keys in your resource trust policy. These keys limit the usage of an IAM policy so that it is used only from Amazon Simple Workflow Service executions that belong in the specified domain ARN. If you use both global condition context keys, the aws:SourceAccount value and the account referenced in the aws:SourceArn value must use the same account ID when used in the same policy statement.

In the following trust policy example, we use the SourceArn context key to restrict the IAM service role to only be used in Amazon Simple Workflow Service executions that belong to someDomain in the account, 123456789012.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "swf.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:swf:*:123456789012:/domain/someDomain" } } } ] }

In the following trust policy example, we use the SourceAccount context key to restrict the IAM service role to only be used in Amazon Simple Workflow Service executions in the account, 123456789012.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "swf.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringLike": { "aws:SourceAccount": "123456789012" } } } ] }

Providing Amazon SWF with access to invoke any Lambda role

You can use the pre-defined role, AWSLambdaRole, to give your Amazon SWF workflows the ability to invoke any Lambda function associated with your account.

To use AWSLambdaRole to give Amazon SWF access to invoke Lambda functions
  1. Open the Amazon IAM console.

  2. Choose Roles, then Create New Role.

  3. Give your role a name, such as swf-lambda and choose Next Step.

  4. Under AWS Service Roles, choose Amazon SWF, and choose Next Step.

  5. On the Attach Policy screen, choose AWSLambdaRole from the list.

  6. Choose Next Step and then Create Role once you've reviewed the role.

Defining an IAM role to provide access to invoke a specific Lambda function

If you want to provide access to invoke a specific Lambda function from your workflow, you will need to define your own IAM policy.

To create an IAM policy to provide access to a particular Lambda function
  1. Open the Amazon IAM console.

  2. Choose Policies, then Create Policy.

  3. Choose Copy an AWS Managed Policy and select AWSLambdaRole from the list. A policy will be generated for you. Optionally edit its name and description to suit your needs.

  4. In the Resource field of the Policy Document, add the ARN of your Lambda function(s). For example:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "lambda:InvokeFunction" ], "Resource": [ "arn:aws:lambda:us-east-1:111111000000:function:hello_lambda_function" ] } ] }
    Note

    For a complete description of how to specify resources in an IAM role, see Overview of IAM Policies in Using IAM.

  5. Choose Create Policy to finish creating your policy.

You can then select this policy when creating a new IAM role, and use that role to give invoke access to your Amazon SWF workflows. This procedure is very similar to creating a role with the AWSLambdaRole policy. instead, choose your own policy when creating the role.

To create a Amazon SWF role using your Lambda policy
  1. Open the Amazon IAM console.

  2. Choose Roles, then Create New Role.

  3. Give your role a name, such as swf-lambda-function and choose Next Step.

  4. Under AWS Service Roles, choose Amazon SWF, and choose Next Step.

  5. On the Attach Policy screen, choose your Lambda function-specific policy from the list.

  6. Choose Next Step and then Create Role once you've reviewed the role.

Attach the IAM role to your workflow

Once you've defined your IAM role, you will need to attach it to the workflow that will be using it to call the Lambda functions you provided Amazon SWF with access to.

There are two places where you can attach the role to your workflow:

  • During workflow type registration. This role then may be used as the default Lambda role for every execution of that workflow type.

  • When starting a workflow execution. This role will be used only during this workflow's execution (and throughout the entire execution).

To provide a default Lambda role for a workflow type
  • When calling RegisterWorkflowType, set the defaultLambdaRole field to the ARN of the role that you defined.

To provide a Lambda role to be used during a workflow execution
  • When calling StartWorkflowExecution, set the lambdaRole field to the ARN of the role that you defined.

Note

if the account calling RegisterWorkflowType or StartWorkflowExecution doesn't have permission to use the given role, then the call will fail with an OperationNotPermittedFault.

Call your Lambda function from a Amazon SWF workflow

You can use the ScheduleLambdaFunctionDecisionAttributes data type to identify the Lambda function to call during a workflow execution.

During a call to RespondDecisionTaskCompleted, provide a ScheduleLambdaFunctionDecisionAttributes to your decisions list. For example:

{ "decisions": [{ "ScheduleLambdaFunctionDecisionAttributes": { "id": "lambdaTaskId", "name": "myLambdaFunctionName", "input": "inputToLambdaFunction", "startToCloseTimeout": "30" }, }], }

Set the following parameters:

  • id with an identifier for the Lambda task. This must be a string from 1-256 characters and must not contain the characters : (colon), / (slash), | (vertical bar), nor any control characters (\u0000 - \u001f and \u007f - \u009f), nor the literal string arn.

  • name with the name of your Lambda function. Your Amazon SWF workflow must be provided with an IAM role that gives it access to call the Lambda function. The name provided must follow the constraints for the FunctionName parameter like in the Lambda Invoke action.

  • input with optional input data for the function. If set, this must follow the constraints for the ClientContext parameter like in the Lambda Invoke action.

  • startToCloseTimeout with an optional maximum period, in seconds, that the function can take to execute before the task fails with a timeout exception. The value NONE can be used to specify unlimited duration.

For more information, see Implementing AWS Lambda Tasks