Implementing AWS Lambda Tasks - AWS Flow Framework for Java
About AWS LambdaBenefits and limitations of using Lambda tasksUsing Lambda tasks in your AWS Flow Framework for Java workflowsView the HelloLambda sample

Implementing 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 AWS Flow Framework for Java workflows

There are three requirements to use Lambda tasks in your AWS Flow Framework for Java workflows:

  • A Lambda function to execute. You can use any Lambda function that you've defined. For more information about how to create Lambda functions, see the AWS Lambda Developer Guide.

  • An IAM role that provides access to execute Lambda functions from your Amazon SWF workflows.

  • Code to schedule the Lambda task from within your workflow.

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.

Schedule a Lambda task for execution

Once you've defined an IAM role that allows you to invoke Lambda functions, you can schedule them for execution as part of your workflow.

Note

This process is fully demonstrated by the HelloLambda sample in the AWS SDK for Java.

To schedule a Lambda task for execution

  1. In your workflow implementation, get an instance of LambdaFunctionClient by calling getLambdaFunctionClient() on a DecisionContext instance.

    
// Get a LambdaFunctionClient instance
DecisionContextProvider decisionProvider = new DecisionContextProviderImpl();
DecisionContext decisionContext = decisionProvider.getDecisionContext();
LambdaFunctionClient lambdaClient = decisionContext.getLambdaFunctionClient();

  2. Schedule the task using the scheduleLambdaFunction() method on the LambdaFunctionClient, passing it the name of the Lambda function that you created and any input data for the Lambda task.

    
// Schedule the Lambda function for execution, using your IAM role for access.
String lambda_function_name = "The name of your Lambda function.";
String lambda_function_input = "Input data for your Lambda task.";

lambdaClient.scheduleLambdaFunction(lambda_function_name, lambda_function_input);

  3. In your workflow execution starter, add the IAM lambda role to your default workflow options by using StartWorkflowOptions.withLambdaRole(), and then pass the options when starting the workflow.

    
// Workflow client classes are generated for you when you use the @Workflow
// annotation on your workflow interface declaration.
MyWorkflowClientExternalFactory clientFactory =
  new MyWorkflowClientExternalFactoryImpl(sdk_swf_client, swf_domain);

MyWorkflowClientExternal workflow_client = clientFactory.getClient();

// Give the ARN of an IAM role that allows SWF to invoke Lambda functions on
// your behalf.
String lambda_iam_role = "arn:aws:iam::111111000000:role/swf_lambda_role";

StartWorkflowOptions workflow_options =
  new StartWorkflowOptions().withLambdaRole(lambda_iam_role);

// Start the workflow execution
workflow_client.helloWorld("User", workflow_options);

View the HelloLambda sample

A sample that provides an implementation of a workflow that uses a Lambda task is provided in the AWS SDK for Java. To view and/or run it, download the source.

A full description of how to build and run the HelloLambda sample is provided in the README file provided with the AWS Flow Framework for Java samples.