Tutorial: Using a cross-account Amazon SQS queue as an event source - AWS Lambda

Tutorial: Using a cross-account Amazon SQS queue as an event source

In this tutorial, you create a Lambda function that consumes messages from an Amazon Simple Queue Service (Amazon SQS) queue in a different AWS account. This tutorial involves two AWS accounts: Account A refers to the account that contains your Lambda function, and Account B refers to the account that contains the Amazon SQS queue.

Prerequisites

This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda console. If you haven't already, follow the instructions in Create a Lambda function with the console to create your first Lambda function.

To complete the following steps, you need the AWS Command Line Interface (AWS CLI) version 2. Commands and the expected output are listed in separate blocks:

aws --version

You should see the following output:

aws-cli/2.13.27 Python/3.11.6 Linux/4.14.328-248.540.amzn2.x86_64 exe/x86_64.amzn.2

For long commands, an escape character (\) is used to split a command over multiple lines.

On Linux and macOS, use your preferred shell and package manager.

Note

In Windows, some Bash CLI commands that you commonly use with Lambda (such as zip) are not supported by the operating system's built-in terminals. To get a Windows-integrated version of Ubuntu and Bash, install the Windows Subsystem for Linux. Example CLI commands in this guide use Linux formatting. Commands which include inline JSON documents must be reformatted if you are using the Windows CLI.

Create the execution role (Account A)

In Account A, create an execution role that gives your function permission to access the required AWS resources.

To create an execution role
  1. Open the Roles page in the AWS Identity and Access Management (IAM) console.

  2. Choose Create role.

  3. Create a role with the following properties.

    • Trusted entityAWS Lambda

    • PermissionsAWSLambdaSQSQueueExecutionRole

    • Role namecross-account-lambda-sqs-role

The AWSLambdaSQSQueueExecutionRole policy has the permissions that the function needs to read items from Amazon SQS and to write logs to Amazon CloudWatch Logs.

Create the function (Account A)

In Account A, create a Lambda function that processes your Amazon SQS messages. The following Node.js 18 code example writes each message to a log in CloudWatch Logs.

Note

For code examples in other languages, see Sample Amazon SQS function code.

Example index.mjs
export const handler = async function(event, context) { event.Records.forEach(record => { const { body } = record; console.log(body); }); return {}; }
To create the function
Note

Following these steps creates a function in Node.js 18. For other languages, the steps are similar, but some details are different.

  1. Save the code example as a file named index.mjs.

  2. Create a deployment package.

    zip function.zip index.mjs
  3. Create the function using the create-function AWS Command Line Interface (AWS CLI) command.

    aws lambda create-function --function-name CrossAccountSQSExample \ --zip-file fileb://function.zip --handler index.handler --runtime nodejs18.x \ --role arn:aws:iam::<AccountA_ID>:role/cross-account-lambda-sqs-role

Test the function (Account A)

In Account A, test your Lambda function manually using the invoke AWS CLI command and a sample Amazon SQS event.

If the handler returns normally without exceptions, Lambda considers the message to be successfully processed and begins reading new messages in the queue. After successfully processing a message, Lambda automatically deletes it from the queue. If the handler throws an exception, Lambda considers the batch of messages not successfully processed, and Lambda invokes the function with the same batch of messages.

  1. Save the following JSON as a file named input.txt.

    { "Records": [ { "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d", "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...", "body": "test", "attributes": { "ApproximateReceiveCount": "1", "SentTimestamp": "1545082649183", "SenderId": "AIDAIENQZJOLO23YVJ4VO", "ApproximateFirstReceiveTimestamp": "1545082649185" }, "messageAttributes": {}, "md5OfBody": "098f6bcd4621d373cade4e832627b4f6", "eventSource": "aws:sqs", "eventSourceARN": "arn:aws:sqs:us-east-1:111122223333:example-queue", "awsRegion": "us-east-1" } ] }

    The preceding JSON simulates an event that Amazon SQS might send to your Lambda function, where "body" contains the actual message from the queue.

  2. Run the following invoke AWS CLI command.

    aws lambda invoke --function-name CrossAccountSQSExample \ --cli-binary-format raw-in-base64-out \ --payload file://input.txt outputfile.txt

    The cli-binary-format option is required if you're using AWS CLI version 2. To make this the default setting, run aws configure set cli-binary-format raw-in-base64-out. For more information, see AWS CLI supported global command line options in the AWS Command Line Interface User Guide for Version 2.

  3. Verify the output in the file outputfile.txt.

Create an Amazon SQS queue (Account B)

In Account B, create an Amazon SQS queue that the Lambda function in Account A can use as an event source.

To create a queue
  1. Open the Amazon SQS console.

  2. Choose Create queue.

  3. Create a queue with the following properties.

    • TypeStandard

    • NameLambdaCrossAccountQueue

    • Configuration – Keep the default settings.

    • Access policy – Choose Advanced. Paste in the following JSON policy:

      { "Version": "2012-10-17", "Id": "Queue1_Policy_UUID", "Statement": [{ "Sid":"Queue1_AllActions", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::<AccountA_ID>:role/cross-account-lambda-sqs-role" ] }, "Action": "sqs:*", "Resource": "arn:aws:sqs:us-east-1:<AccountB_ID>:LambdaCrossAccountQueue" } ] }

      This policy grants the Lambda execution role in Account A permissions to consume messages from this Amazon SQS queue.

  4. After creating the queue, record its Amazon Resource Name (ARN). You need this in the next step when you associate the queue with your Lambda function.

Configure the event source (Account A)

In Account A, create an event source mapping between the Amazon SQS queue in Account B and your Lambda function by running the following create-event-source-mapping AWS CLI command.

aws lambda create-event-source-mapping --function-name CrossAccountSQSExample --batch-size 10 \ --event-source-arn arn:aws:sqs:us-east-1:<AccountB_ID>:LambdaCrossAccountQueue

To get a list of your event source mappings, run the following command.

aws lambda list-event-source-mappings --function-name CrossAccountSQSExample \ --event-source-arn arn:aws:sqs:us-east-1:<AccountB_ID>:LambdaCrossAccountQueue

Test the setup

You can now test the setup as follows:

  1. In Account B, open the Amazon SQS console.

  2. Choose LambdaCrossAccountQueue, which you created earlier.

  3. Choose Send and receive messages.

  4. Under Message body, enter a test message.

  5. Choose Send message.

Your Lambda function in Account A should receive the message. Lambda will continue to poll the queue for updates. When there is a new message, Lambda invokes your function with this new event data from the queue. Your function runs and creates logs in Amazon CloudWatch. You can view the logs in the CloudWatch console.

Clean up your resources

You can now delete the resources that you created for this tutorial, unless you want to retain them. By deleting AWS resources that you're no longer using, you prevent unnecessary charges to your AWS account.

In Account A, clean up your execution role and Lambda function.

To delete the execution role
  1. Open the Roles page of the IAM console.

  2. Select the execution role that you created.

  3. Choose Delete.

  4. Enter the name of the role in the text input field and choose Delete.

To delete the Lambda function
  1. Open the Functions page of the Lambda console.

  2. Select the function that you created.

  3. Choose Actions, Delete.

  4. Type delete in the text input field and choose Delete.

In Account B, clean up the Amazon SQS queue.

To delete the Amazon SQS queue
  1. Sign in to the AWS Management Console and open the Amazon SQS console at https://console.aws.amazon.com/sqs/.

  2. Select the queue you created.

  3. Choose Delete.

  4. Enter confirm in the text input field.

  5. Choose Delete.