What is the AWS SAM CLI?

Last week, Emma Button, nubeGo’s COO posted a personal tutorial of how to make a simple serverless Slack integration using AWS Lambda and the Serverless Application Model (SAM) CLI. In this blog post, Emma explains a little more about what SAM is, and demonstrates the CLI tools available to help developers get up and running building serverless applications in AWS.

Simple serverless application using AWS SAM

The Serverless Application Model (SAM) is an opensource framework that makes it easy to describe and build serverless applications that include compute functions, serverless storage and interfaces into them, such as an API Gateway. SAM uses a declarative framework (built on top of AWS Cloudformation) that allows you to put together a description of your desired service and the resources it depends on, and then send this off to various different tools for deployment into AWS.

The easiest way to understand SAM is to use the SAM command line interface (CLI) to programmatically create a straightforward Hello World lambda function without any need to log into your AWS console at all. In my blog post, I walked through the steps needed to create a simple Slack integration in a Lambda function and the process is very similar.

Before creating your SAM application you will need the following things:-

• Docker running on your machine (so that you can make the most of SAM)

• The AWS CLI installed on your machine (or an AWS Cloud 9 environment!) and configured with an Access Key and Secret Access Key for your AWS account that has permissions to perform Lambda administrative actions

• The SAM CLI installed on your machine

• npm installed on your machine

Step 1 - Create a Skeleton SAM App

Creating a Serverless Application Model (SAM) App on the command line is incredibly straightforward. The easiest place to start is with a standard AWS template. From the command line, running

sam init

Follow the on-screen prompts. In this example, I chose to use the AWS Quickstart Templates and a nodejs12.x runtime and called my app *nubego-fun*.

sam init will create you a directory that includes the code for your Lambda, a SAM template, a sample input event and a sample unit test. The first thing I did was to rename the folders and files to replace:

hello-world = nubego-fun-app

hello = nubego

HelloWorld = NubeGoFun

Hello World = NubeGo Fun

At this point, my template.yml looks like this:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
  nubego-fun

  Sample SAM Template for nubego-fun
  
Globals:
  Function:
    Timeout: 30

Resources:
  NubeGoFunFunction:
    Type: AWS::Serverless::Function 
    Properties:
      CodeUri: nubego-fun-app/
      Handler: app.lambdaHandler
      Runtime: nodejs12.x
      Events:
        HelloWorld:
          Type: Api 
          Properties:
            Path: /nubego
            Method: get

Outputs:
  NubeGoFunApi:
    Description: "API Gateway endpoint URL for Prod stage for nubeGo Fun function"
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/nubego/"
  NubeGoFunFunction:
    Description: "Nubego Fun Lambda Function ARN"
    Value: !GetAtt NubeGoFunFunction.Arn
  NubeGoFunFunctionIamRole:
    Description: "Implicit IAM Role created for Nubego Fun function"
    Value: !GetAtt NubeGoFunFunctionRole.Arn

Before you run the next step, you need to make sure that the default profile for your AWS command line is pointing to a user and account in AWS that has permissions to create Lambda and IAM roles. You can check this by running aws configure from the command line, or examining the .credentials file containing your AWS CLI profiles.

Now build your app. From within the folder containing your template.yaml file for your app, run

sam build

And then finally deploy it

sam deploy --guided

Follow the prompts. Give your app a name that you will recognise in the AWS console, choose the region you'd like to deploy to, and make sure to say Y to allow SAM to create IAM roles on your behalf.

Note: once you have deployed your app once and selected your deployment options, you no longer need to use the --guided option for future deployments.

When your deployment completes, it should show you a series of outputs, one of these will be the HTTP endpoint of the API Gateway that has been magically created on your behalf, something a little bit like.

https://somethinghere.execute-api.eu-west-2.amazonaws.com/Prod/nubego/

Try accessing your endpoint now using the curl command or your browser.

{"message":"hello world"}

When you access the HTTP endpoint, your request is forwarded from API Gateway straight to your lambda function. To customise your lambda function you can now edit the handler inside app.js. Now is a good time to browse through your AWS account and have a look at all the resources that were created by SAM using Cloudformation. Check out the IAM roles, Lambda functions and API gateway services in your AWS Console.

Step 2 - Testing your SAM App Locally

Perhaps the most awesome thing about using the SAM CLI is the ability to test your Lambda functions locally and remotely. Inside your generated code you may notice that SAM has created you a unit test and some sample events to be sent to your lambda function. To see this in action run:

sam local start-api

This will start up a local server running on your own machine with your HTTP endpoint now exposed and accessible at http://127.0.0.1:3000/nubego. You can test your whole SAM application locally this way, or use start-lambda to start a specific lambda only.

Alternatively, you might just want to test out a single Lambda function before you deploy it to AWS (perhaps from a unit test). You can do that by invoking the lambda function locally directly using the SAM CLI:

sam local invoke "NubeGoFunFunction" -e events/event.json

Under the covers, this starts up a Docker container on your machine that contains your function under test. It is a quick and easy way of testing the output from a lambda function without having to go anywhere near your AWS account!

This is just the beginning of your serverless application model journey. SAM templates integrate well with the AWS CodeBuild and CodeDeploy tools and with the IDE tools, for example the IntelliJ plugin. If you'd like to see some examples of what can be achieved using SAM, take a look at the AWS SAM repository. Ask nubeGo for further advice on your Serverless development journey with expert guidance on AWS Training and DevOps.