Lambda-SNS starter project

This project contains source code and supporting files for the serverless application that you created in the AWS Lambda console. You can update your application at any time by committing and pushing changes to your AWS CodeCommit or GitHub repository.

This project includes the following files and folders:

• src - Code for the application's Lambda function.
• events - Invocation events that you can use to invoke the function.
• __tests__ - Unit tests for the application code.
• template.yml - A SAM template that defines the application's AWS resources.
• buildspec.yml - A build specification file that tells AWS CodeBuild how to create a deployment package for the function.

Your Lambda application includes two AWS CloudFormation stacks. The first stack creates the pipeline that builds and deploys your application.

The pipeline creates a second stack that contains your application's resources, including Lambda functions, and an Amazon SNS topic. These resources are defined in the template.yml file in this project. You can update the template to add AWS resources through the same deployment process that updates your application code. You can view those resources in the Resources section of the application overview in the Lambda console.

For a full list of possible operations, see the AWS Lambda Applications documentation.

Try the application out

1. Go to the Lambda console.
2. Select Applications and select the one you created.
3. Select SimpleTopic in Resources table, which will redirect you to the SNS console.
4. Click on the SimpleTopic in the list, then Publish message in the top right.
5. Enter any text you'd like in message body, then click Publish message.
6. Go back to the Lambda console, find your application again and click it.
7. Select snsPayloadLoggerFunction in the Resources table.
8. On the new page, select the Monitoring tab, then click View Logs in CloudWatch, which will take you to the CloudWatch Logs console.
9. Click on the latest log stream entry, and you will find your log statement.

Add a resource to your application

The application template uses the AWS Serverless Application Model (AWS SAM) to define application resources. AWS SAM is an extension of AWS CloudFormation with a simpler syntax for configuring common serverless application resources, such as functions, triggers, and APIs. For resources that aren't included in the AWS SAM specification, you can use the standard AWS CloudFormation resource types.

Update template.yml to add a dead-letter queue to your application. In the Resources section, add a resource named MyQueue with the type AWS::SQS::Queue.

Resources:
  MyQueue:
    Type: AWS::SQS::Queue

The dead-letter queue is a location for Lambda to send events that could not be processed. It's only used if you invoke your function asynchronously, but it's useful here to show how you can modify your application's resources and function configuration.

Commit the change and push.

my-application$ git commit -am "Add dead-letter queue."
my-application$ git push

To see how the pipeline processes and deploys the change

1. Open the Applications page.
2. Choose your application.
3. Choose Deployments.

When the deployment completes, view the application resources on the Overview tab to see the new resource.

Update the permissions boundary

The sample application applies a permissions boundary to its function's execution role. The permissions boundary limits the permissions that you can add to the function's role. Without the boundary, users with write access to the project repository could modify the project template to give the function permission to access resources and services outside of the scope of the sample application.

In order for the function to use the queue that you added in the previous step, you must extend the permissions boundary. The Lambda console detects resources that aren't in the permissions boundary and provides an updated policy that you can use to update it.

To update the application's permissions boundary

1. Open the Applications page.
2. Choose your application.
3. Choose Edit permissions boundary.
4. Follow the instructions shown to update the boundary to allow access to the new queue.

Update the function configuration

Now you can grant the function permission to access the queue and configure the dead-letter queue setting.

In the function's properties in template.yml, add the DeadLetterQueue configuration. Under Policies, add SQSSendMessagePolicy. SQSSendMessagePolicy is a policy template that grants the function permission to send messages to a queue.

Resources:
  MyQueue:
    Type: AWS::SQS::Queue
  snsPayloadLoggerFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./
      Handler: src/handlers/sns-payload-logger.snsPayloadLoggerHandler
      Runtime: nodejs10.x
      Description: A Lambda function that logs the payload of messages sent to an associated SNS topic.
      MemorySize: 128
      Timeout: 60
      DeadLetterQueue:
        Type: SQS
        TargetArn: !GetAtt MyQueue.Arn
      Policies:
        - SQSSendMessagePolicy:
            QueueName: !GetAtt MyQueue.QueueName
        - AWSLambdaBasicExecutionRole
      Events:
        SimpleTopicEvent:
          Type: SNS
          Properties:
            Topic: !Ref SimpleTopic

Commit and push the change. When the deployment completes, view the function in the console to see the updated configuration that specifies the dead-letter queue.

Build and test locally

The AWS SAM command line interface (CLI) is an extension of the AWS CLI that adds functionality for building and testing Lambda applications. It uses Docker to run your functions in an Amazon Linux environment that matches Lambda. It can also emulate your application's build environment and API.

If you prefer to use an integrated development environment (IDE) to build and test your application, you can use the AWS Toolkit. The AWS Toolkit is an open-source plugin for popular IDEs that uses the AWS SAM CLI to build and deploy serverless applications on AWS. The AWS Toolkit also adds step-through debugging for Lambda function code.

To get started, see the following:

• PyCharm
• IntelliJ
• VS Code
• Visual Studio

To use the AWS SAM CLI with this sample, you need the following tools:

• AWS CLI - Install the AWS CLI and configure it with your AWS credentials.
• AWS SAM CLI - Install the AWS SAM CLI.
• Docker - Install Docker community edition.

Build your application with the sam build command.

my-application$ sam build -m package.json

The AWS SAM CLI installs dependencies that are defined in package.json, creates a deployment package, and saves its contents in the .aws-sam/build folder.

Test a single function by invoking it directly with a test event. An event is a JSON document that represents the input that the function receives from the event source. Test events are included in the events folder in this project.

Run functions locally and invoke them with the sam local invoke command.

my-application$ sam local invoke snsPayloadLoggerFunction --event events/event-sns.json

Unit tests

Requirements:

• Node.js - Install Node.js 10, including the npm package management tool.

Tests are defined in the __tests__ folder in this project. Use npm to install the Jest test framework and run unit tests.

my-application$ npm install
my-application$ npm run test

Resources

For an introduction to the AWS SAM specification, the AWS SAM CLI, and serverless application concepts, see the AWS SAM Developer Guide.

Next, you can use the AWS Serverless Application Repository to deploy ready-to-use apps that go beyond Hello World samples and learn how authors developed their applications. For more information, see the AWS Serverless Application Repository main page and the AWS Serverless Application Repository Developer Guide.