This site uses cookies. Continue to use the site as normal if you are happy with this, or read more about cookies and how to manage them.

×

This site uses cookies. Continue to use the site as normal if you are happy with this, or read more about cookies and how to manage them.

×

Getting Started with AWS SAM

AWS Lambda is Amazon's function as a service (FaaS) offering, and recently I've been playing around with it. I've used Lambda in the past for really bite-sized applications, however I've always been hesitant to use the technology to create anything too complex. There are a few reasons for this. I found it difficult to run and debug a Lambda locally in a manner comparable to a production like setting. Also, interacting with other AWS resources locally without embedding AWS credentials in my code, risking accidentally committing them into source control can be a nuisance.

Then I discovered AWS SAM. AWS Serverless Application Model (SAM), is an open-source framework that focuses on providing developer-friendly tools to create serverless applications on AWS. It utilises Docker to emulate an environment akin to a deployed AWS Lambda, allowing us to develop, run, test and deploy a serverless application with ease. In this blog I'm going to demonstrate how to get up and running with AWS SAM, along with its benefits and its weaknesses.

Pre-reqs

In order to play along, install the following:

Ensure AWS credentials are set up by running aws configure.

Getting Started

Initialise a sample AWS SAM project by running sam init. This will create a new directory named "sam-app". If we enter this directory, we will see the following files:

.
├── README.MD                   <-- Instructions for SAM project
├── event.json                  <-- A sample event payload for API Gateway
├── hello-world                 <-- Source code for a lambda function
│   └── app.js                  <-- Lambda function code
│   └── package.json            <-- NodeJS dependencies and scripts
│   └── tests                   <-- Unit tests
│       └── unit
│           └── test-handler.js
├── template.yaml               <-- SAM template

This command generated a SAM project consisting of a NodeJS application configured with one API Gateway endpoint on /hello that responds with a HTTP 200 with message "hello world".

Note: Throughout this blog I will be sticking with NodeJS as the runtime, because it is the default, however SAM also supports: Java, C#, Powershell, Go, Ruby, and Python.

Up and Running

SAM bakes in best practise for AWS, it enforces the use of infrastructure as code using a wrapper of CloudFormation templates named SAM templates. If we open our SAM template: template.yaml, we'll see the following:

HelloWorldFunction:               <-- Name of our function
    Type: AWS::Serverless::Function <-- Type of resource
    Properties:
      CodeUri: hello-world/ 
      Handler: app.lambdaHandler    <-- app is hello-world/app.js, lambdaHandler is exported function in app.js
      Runtime: nodejs8.10           <-- Runtime of our Lambda
      Events:                       <-- All endpoints
        HelloWorld:                 <-- Endpoint name
          Type: Api
          Properties:
            Path: /hello            <-- Endpoint path
            Method: get             <-- Endpoint method

The AWS::Serverless::Function resource type is a really concise way of creating an API Gateway instance with an endpoint, a Lambda to execute our code and an IAM Role to allowing for the permissions to run the Lambda and write logs to CloudWatch. The "HelloWorldFunction" resource executes the lambdaHandler function in app.js, on an HTTP GET request to /hello.

Now that we understand what our SAM app is doing, lets run it! Run: sam local start-api, visit http://localhost:3000/hello and behold... hello world.

Let's open our app.js file and change "hello world" to "greetings world", save the file, then refresh http://localhost:3000/hello . See how the greeting has changed? Nice, no need to restart to server or any other nonsense for code changes, (though it's worth noting that restarting the server is required for changes to the template.yaml file).

So we can run our Lambda locally and experience hot reloading on our code changes. This already severely beats my previous approach to Lambda development where I had to manually upload my code changes to Lambda every time I wanted to run my application in a production-like setting.

Debugging

AWS SAM also gives us the tools to debug our Lambdas, instead of entirely relying on the ol' console.log(). The AWS Toolkit Plugin can be installed for a number of different IDEs/text editors to make debugging easier in, for example, Visual Studio Code, IntelliJ, PyCharm. Since we are creating our application using Node, my example here will be demonstrating debugging using Visual Studio Code, however AWS documentation specifies in detail the process for other IDEs.

To begin debugging our Lambdas in VSCode, first open the sam-app project in VSCode. Following this, we'll need to select to the Debug icon on the left toolbar, (or Ctrl+Shift+D). Open the dropdown next to the text Debug and select Add Configuration. This will open up a text editor for launch.json, paste the following JSON:

{
    "version": "0.2.0",
    "configurations": [
        
        {
            "name": "Attach to SAM CLI",
            "type": "node",
            "request": "attach",
            "address": "localhost",
            "port": 5858,
            "localRoot": "${workspaceRoot}/hello-world",
            "remoteRoot": "/var/task",
            "protocol": "inspector",
            "stopOnEntry": false
        }
    ]
}

Note: The localRoot property value "hello-world" should be changed to the name of the directory containing our Lambda application code.

Then run our Lambdas locally with the debug flag at port 5858: sam local start-api -d 5858. Once this is running, add a breakpoint to a line in our Lambda function, then hit the Play icon on the Attach to SAM CLI configuration we just added. Finally invoke the function e.g. visit http://localhost:3000/hello and we can start debugging our Lambda within VSCode.

This GIF on AWS documentation runs through the whole debugging process quite nicely.

SAM Debugging

Deploying

In order to deploy the application, we must create an S3 bucket to contain our application code along with its dependencies. Run aws s3 mb s3://BUCKET_NAME to create an S3 bucket.

Note: BUCKET_NAME should be replaced with a more suitable name.

Next, run: sam package --output-template-file packaged.yaml --s3-bucket BUCKET_NAME. This long command will do a few things. It will upload our application code with its dependencies to our S3 bucket, then it will convert our SAM template to a CloudFormation template named packaged.yaml, updating the CodeUri property to point to our S3 bucket when our application code now resides.

Finally, run sam deploy --template-file packaged.yaml --stack-name sam-app --capabilities CAPABILITY_IAM. This command is a wrapper around the aws cloudformation deploy command and simply deploys a stack, in this case called sam-app, from the packaged.yaml template file with the permissions to create IAM resources and schedules our specified resources to be created. You can visit the CloudFormation page in the AWS Console to view the progress of resource creation. Once our resources have been successfully created, we can click Outputs, then click the url titled HelloWorldApi to execute the deployed Lambda.

Interact with Other AWS Resources

So we have deployed our application and greeted the world. Greeting the world is a little impersonal though, let's add DynamoDB so we can greet specific people by their real names! AWS SAM makes this really easy and allows us to run our Lambda locally against AWS resources, without the need of AWS credentials.

Add the following to our template.yml within the Resources section:

Resources:
  ...
    NamesTable:
      Type: AWS::Serverless::SimpleTable
      Properties:
        TableName: Names
        PrimaryKey:
          Name: id
          Type: String
        ProvisionedThroughput:
          ReadCapacityUnits: 5
          WriteCapacityUnits: 5
        SSESpecification:
          SSEEnabled: true

This will create a simple DynamoDB table with a single primary key, named id in this case. Before we continue, deploy these changes to actually create the DynamoDB table. Our Lambda will need it to actually exist in order to interact with it.

Note: It is possible to start a local Docker container version of DynamoDB and run a Lambda locally against it, however AWS SAMs tooling does not help with this and it is our responsibility to ensure the Lambda container and DynamoDB container can actually see each other. Conditional logic in the Lambda to connect to the local DynamoDB Docker container if you are running the Lambda locally, else in production, connect to the real DynamoDB would also be required. I did experiment with this but concluded that it was just easier to run a Lambda locally against real AWS resources.

Now we need an additional Lambda to write names of people that need to be greeted to this shiny new database table. Since this Lambda needs to be able to write to our database, it needs the have appropriate IAM Role. Luckily AWS SAM makes this really simple.

Add the following code to our template.yml in the resources section:

Resources:
  ...
    AddNameFunction:
      Type: AWS::Serverless::Function
      Properties:
        CodeUri: hello-world/
        Handler: app.addName
        Runtime: nodejs8.10
        Policies:
          - DynamoDBCrudPolicy:
              TableName: !Ref NamesTable
        Events:
          HelloWorld:
            Type: Api
            Properties:
              Path: /add-name
              Method: post

This will create a new API Gateway endpoint /add-name that will accept HTTP POST requests and runs the function addName in app.js. Notice the predefined DynamoDBCrudPolicy in the Policy section; AWS SAM has a bunch of pre-canned policies for access to common services, like the one we defined on NamesTable for DynamoDB CRUD operations. You can view the other Policy Templates here.

Time to actually create our addNames function. First install the AWS SDK: npm install aws-sdk, then we can write the following code:

const AWS = require('aws-sdk');
const db = new AWS.DynamoDB.DocumentClient();
...
exports.addName = async (event, context) => {
    let response;
    const { name } = JSON.parse(event.body); // fetch name property from POST request body
    const id = Buffer.from(name).toString('base64'); // base64 name to get unique id

    const params = {
        TableName: 'Names',
        Item: {
            id,
            name
        }
    };

    try {
        await db.put(params).promise();
        response = {
            statusCode: 201,
        };
    } catch (err) {
        response = {
            statusCode: 500,
            body: JSON.stringify({ message: err.message })
        };
    }

    return response;
}

Now when we perform a HTTP POST to http://localhost:3000/add-name with a JSON body of: { "name": "BoJack Horseman" }, we should get a new entry in our table for Mr Horseman himself. Try it out.

Now let's add a new Lambda to read from our Names table and greet those lucky few. Add the following to our template.yml:

Resources:
  ...
    GreetNamesFunction:
      Type: AWS::Serverless::Function
      Properties:
        CodeUri: hello-world/
        Handler: app.greetNames
        Runtime: nodejs8.10
        Policies:
          - DynamoDBCrudPolicy:
              TableName: !Ref NamesTable
        Events:
          HelloWorld:
            Type: Api
            Properties:
              Path: /greet-names
              Method: get

Then let's write the function itself:

exports.greetNames = async (event, context) => {
    let response;

    try {
        const names = (await db.scan({ TableName: 'Names' }).promise())
            .Items.map((item) => item.name);

        response = {
            statusCode: 200,
            body: JSON.stringify({ message: `hello ${names}` })
        };
    } catch (err) {
        response = {
            statusCode: 500,
            body: JSON.stringify({
                message: err.message,
            })
        }
    }

    return response;
}

This function simply fetches all items from our Names table, maps the name property and then returns a greeting with all the names.

Let's also add the URLs for our new endpoints in the Outputs section so we can easily access them when we deploy:

Outputs:
    ...
    GreetNamesApi:
      Description: "API Gateway endpoint URL for Prod stage for Greet Names function"
      Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/greet-names/"
    AddNameApi:
      Description: "API Gateway endpoint URL for Prod stage for Add Name function"
      Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/add-name/"
  ...

Now all is left to do is to deploy, get the URLs from the Outputs section in the AWS Console CloudFormation page and try out our Lambdas in the wild.

So here we have demonstrated that we can interact with AWS resources whilst running Lambda locally, purely using IAM Roles. This approach is recommended by AWS themselves and eliminates the risk of misplacing AWS credentials.

Conclusion

There is no question that AWS SAM vastly improves developer experience when creating Lambdas. I can speak with certainty when declaring that all future Lambdas I personally work on will be creating via AWS SAM. This blog demonstrates the removal of my hesitations regarding running, debugging Lambdas locally in a manner comparable to production, and interacting with other AWS resources locally without AWS credentials. So is it time to abandon tried and tested frameworks like Spring, Express and Django in favour of Lambda supported by AWS SAM? Like many aspects of software development, there isn't a clear cut yes or no answer to that question. I'd rather answer with a "sometimes...", trailing off and looking deep in thought.

Lambda can be described as a function in the sky, and whilst this is an incredible feat in itself, it is not without weakness. It's just standalone plain code. You do not get to enjoy the rich, crafted tooling a framework like Spring, Django and Express give out of the box. Common problems like dependency management become harder because they aren't solved for you. You have to go into the wild and find standalone dependencies that meet your requirements or roll your own solution. Now this isn't so much an issue for every application, especially smaller scale applications, but for larger scale applications, the appeal for the batteries included approach a framework provides is still attractive.

The source code can be found at: https://github.com/Mouzourides/aws-sam-hello-world