In this workshop series, we build CI/CD for NodeJS serverless applications.
In order to complete this workshop, you’ll need access to an AWS account. Your access needs to have sufficient permissions to create resources in IAM, CloudFormation, API Gateway, CodeCommit, CodePipeline, CodeBuild, CodeDeploy and S3.
If you currently don’t have an AWS account, you can create one here.
If you prefer to run the workshop from your local computer without using Cloud9, make sure you install the following tools which are available for Linux, MacOS and Windows.
Docker Desktop - Required to simulate the Lambda runtime locally.
SAM CLI v0.31.0+ - To run functions locally and package/deploy SAM apps.
AWS CLI - To create resources in your AWS account.
Git Client - To interact with the CodeCommit repository by pushing code changes.
NodeJS and npm - The sample app you will create is NodeJs-based.
The AWS Serverless Application Model (AWS SAM) is an open-source framework that developers use to build production-grade serverless applications on AWS.
A serverless application is a combination of Lambda functions, event sources, and other resources that work together to perform tasks. But a serverless application is more than just a Lambda function—it can include additional resources such as APIs, databases, and event source mappings.
In this first part of workshop series, you will learn how to quickly scaffold a SAM application and understand how it is structured.
AWS SAM provides you with a command line tool, the AWS SAM CLI, that makes it easy for you to create and manage serverless applications. It particularly makes easy the scaffolding of a new project, as it creates the initial skeleton of a hello world application, so you can use it as a baseline and continue building your project from there.
Run the following command to scaffold a new project:
It will prompt for project configuration parameters:
Type 1 to select AWS Quick Start Template
Type 1 to select Zip as the package type
Type 1 to select the Hello World Example
Project should now be initialized
The Hello World SAM project you just created will create the following architecture when deployed. It has a single Lambda function, an API Gateway that exposes a /hello resource and invokes the Lambda function when called with an HTTP GET request. The Lambda function assumes an IAM role that can have permissions to interact with other AWS resources, like a database for example.
Now, let's explore the the SAM template.
It should have a structure like the following.
You may notice that the syntax looks exactly like AWS CloudFormation, this is because SAM templates are an extension of CloudFormation templates. That is, any resource that you can declare in CloudFormation, you can also declare in a SAM template. Let’s take a closer look at the components of the template.
Notice the transform line of the template, it tells CloudFormation that this template adheres to the open source AWS Serverless Application Model specification.
This section defines properties common to all your Serverless functions and APIs. In this case, it’s specifying that all functions in this project will have a default timeout of 3 seconds.
The following section creates a Lambda function with an IAM execution role. It also specifies that the code for this Lambda function is located under a folder named hello-world, and that its entrypoint is a function named lambdaHandler within a file named app.js.
Notice that the IAM role is not explicitly specified, this is because SAM will create a new one by default. You can override this behavior and pass your own role by specifying the Role parameter. For a complete list of the parameters you can specify for a Lambda function check the SAM reference.
This section is part of the function definition and it specifies the different events that will trigger the Lambda function. In this case, we are specifying the event to be an API Gateway with an endpoint on /hello that will listen on HTTP method GET.
The Outputs section is optional and it declares output values that you can import into other CloudFormation stacks (to create cross-stack references), or simply to view them on the CloudFormation console. In this case we are making the API Gateway endpoint URL, the Lambda function ARN and the IAM Role ARN available as Outputs to make them easier to find.
Let’s take a look at the code of the Hello World Lambda function. Open the file app.js under the hello-world folder. Note that your function may have additional commented out code, those lines have been removed from the following example for clarity:
#### The Lambda handler
The handler is the method in your Lambda function that processes events. When you invoke a function, the runtime runs the handler method. When the handler exits or returns a response, it becomes available to handle another event. In this case, the lambda handler is the lambdaHandler function, as specified in the SAM template.yaml.
The first argument passed to the handler function is the event object, which contains information from the invoker. In this case, the invoker is API Gateway, which passes the HTTP request information as a JSON-formatted string, and the Lambda runtime converts it to an object.
The second argument is the context object, which contains information about the invocation, function, and execution environment. You can get information like the CloudWatch log stream name or the remaining execution time for the function.
API Gateway expects the handler to return a response object that contains statusCode and body, but it can also contain optional headers.