resourceful

Little functions doing big things.

Overview

Below is a brief explanation of the project structure:

.
├── README.MD                   <-- This instructions file
├── <lambda-sub-folder>-XX      <-- Source code for a NodeJS lambda function
│   └── app.js                  <-- Lambda function code
│   └── package.json            <-- NodeJS dependencies and scripts
├── template.yaml               <-- SAM template
├── .github                     <-- Github Actions
│   └── workflows               <-- Workflows root directory
│       └── <action>.yml        <-- Action defintion file

Requirements

• AWS CLI configured with Administrator permission

Setup process

• Install AWS CLI, run aws configure and enter credentials from your AWS service account.
• Install SAM (Server Application Model) CLI.

Optional Setup for VSCode users

• Install the AWS Toolkit for Visual Studio Code plugin. This is handy if you're learning the AWS/SAM CLI tools.

Packaging and deployment

Firstly, we need a S3 bucket where we can upload our Lambda functions packaged as ZIP before we deploy anything - If you don't have a S3 bucket to store code artifacts then this is a good time to create one:

aws s3 mb s3://BUCKET_NAME

Using the VSCode extention

Click on the AWS Toolkit Icon on the sidebar, then click the elipises symbol (...) in the top right corner and click Deploy SAM Application.

Using Github Actions

Add your AWS credentials to Github secrets then configure Github workflows.

Using command line tools

AWS Lambda runtime requires a flat folder with all dependencies including the application. SAM will use CodeUri property to know where to look up for both application and dependencies:

...
    HelloWorldFunction:
        Type: AWS::Serverless::Function
        Properties:
            CodeUri: hello-world/
            ...

Next, run the following command to package our Lambda function to S3:

sam package \
    --output-template-file packaged.yaml \
    --s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME

Next, the following command will create a Cloudformation Stack and deploy your SAM resources.

sam deploy \
    --template-file packaged.yaml \
    --stack-name yourself \
    --capabilities CAPABILITY_IAM

See Serverless Application Model (SAM) HOWTO Guide for more details in how to get started.

After deployment is complete you can run the following command to retrieve the API Gateway Endpoint URL:

aws cloudformation describe-stacks \
    --stack-name yourself \
    --query 'Stacks[].Outputs[?OutputKey==`HelloWorldApi`]' \
    --output table

Fetch, tail, and filter Lambda function logs

To simplify troubleshooting, SAM CLI has a command called sam logs. sam logs lets you fetch logs generated by your Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug.

NOTE: This command works for all AWS Lambda functions; not just the ones you deploy using SAM.

sam logs -n HelloWorldFunction --stack-name yourself --tail

You can find more information and examples about filtering Lambda function logs in the SAM CLI Documentation.

Testing

We use mocha for testing our code and it is already added in package.json under scripts, so that we can simply run the following command to run our tests:

cd hello-world
npm install
npm run test

Cleanup

In order to delete our Serverless Application recently deployed you can use the following AWS CLI Command:

aws cloudformation delete-stack --stack-name yourself

Bringing to the next level

Here are a few things you can try to get more acquainted with building serverless applications using SAM:

Installing dependencies

• If using Github Actions, packages defined in package.json will be installed during deployment.
• If using SAM CLI, AWS CLI or VSCode extention plugin, each lambda must have a node_modules/ directory in its respective sub-folder.

Step-through debugging

• Enable step-through debugging docs for supported runtimes

Next, you can use AWS Serverless Application Repository to deploy ready to use Apps that go beyond hello world samples and learn how authors developed their applications: AWS Serverless Application Repository main page

Appendix

Building the project

AWS Lambda requires a flat folder with the application as well as its dependencies in a node_modules folder. When you make changes to your source code or dependency manifest, run the following command to build your project local testing and deployment:

sam build

If your dependencies contain native modules that need to be compiled specifically for the operating system running on AWS Lambda, use this command to build inside a Lambda-like Docker container instead:

sam build --use-container

By default, this command writes built artifacts to .aws-sam/build folder.

SAM and AWS CLI commands

All commands used throughout this document

# Invoke function locally with event.json as an input
sam local invoke HelloWorldFunction --event event.json

# Run API Gateway locally
sam local start-api

# Create S3 bucket
aws s3 mb s3://BUCKET_NAME

# Package Lambda function defined locally and upload to S3 as an artifact
sam package \
    --output-template-file packaged.yaml \
    --s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME

# Deploy SAM template as a CloudFormation stack
sam deploy \
    --template-file packaged.yaml \
    --stack-name yourself \
    --capabilities CAPABILITY_IAM

# Describe Output section of CloudFormation stack previously created
aws cloudformation describe-stacks \
    --stack-name yourself \
    --query 'Stacks[].Outputs[?OutputKey==`HelloWorldApi`]' \
    --output table

# Tail Lambda function Logs using Logical name defined in SAM Template
sam logs -n HelloWorldFunction --stack-name yourself --tail

NOTE: Alternatively this could be part of package.json scripts section.