Using SAM to create a serverless application with API Gateway and Lambda
In the following pages, we have covered how to create a serverless app using API Gateway and Lambda, and now we would like to reproduce a similar configuration using SAM.
SAM (Serverless Application Model) is a framework for developing serverless application applications provided by AWS.
The AWS Serverless Application Model (SAM) is an open-source framework for building serverless applications. It provides shorthand syntax to express functions, APIs, databases, and event source mappings… During deployment, SAM transforms and expands the SAM syntax into AWS CloudFormation syntax, enabling you to build serverless applications faster.
AWS Serverless Application Model
In this page, we will check SAM by following the steps in the official AWS tutorial Tutorial: Deploying a Hello World application.
Environment
We will build the same environment as in Serverless Application using Lambda and API Gateway.
We will create the application with the following settings.
- Application name: fa-006
- Runtime environment for Lambda functions: Python 3.8
SAM application creation
Create an application with AWS SAM CLI.
If you have not installed this tool, please refer to Installing the AWS SAM CLI.
$ sam init
Which template source would you like to use?
1 - AWS Quick Start Templates
2 - Custom Template Location
Choice: 1
What package type would you like to use?
1 - Zip (artifact is a zip uploaded to S3)
2 - Image (artifact is an image uploaded to an ECR image repository)
Package type: 1
Which runtime would you like to use?
1 - nodejs12.x
2 - python3.8
3 - ruby2.7
4 - go1.x
5 - java11
6 - dotnetcore3.1
7 - nodejs10.x
8 - python3.7
9 - python3.6
10 - python2.7
11 - ruby2.5
12 - java8.al2
13 - java8
14 - dotnetcore2.1
Runtime: 2
Project name [sam-app]: fa-006
Cloning app templates from https://github.com/aws/aws-sam-cli-app-templates
AWS quick start application templates:
1 - Hello World Example
2 - EventBridge Hello World
3 - EventBridge App from scratch (100+ Event Schemas)
4 - Step Functions Sample App (Stock Trader)
5 - Elastic File System Sample App
Template selection: 1
-----------------------
Generating application:
-----------------------
Name: fa-006
Runtime: python3.8
Dependency Manager: pip
Application Template: hello-world
Output Directory: .Code language: Bash (bash)SAM configuration file
Place the SAM template file at the following URL.
Template file points
We will cover the key points of each template file to configure this environment.
Lambda functions are defined with AWS::Serverless::Function type
Define a Lambda function in SAM.
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello_world/
Handler: app.lambda_handler
Runtime: python3.8
Events:
HelloWorld:
#Type: Api
Type: HttpApi
Properties:
Path: /hello
Method: getCode language: YAML (yaml)In CloudFormation, the Type property specifies the type of resource to be created. Normally, when defining a Lambda function, “AWS::Lambda::Function” is used, but if you follow the SAM notation, it will be “AWS::Serverless::Function”.
In the CodeUri property, specify the directory PATH where the script to be executed is located. PATH can be specified relative to this template file. The PATH can be specified relative to the main template file. In this case, it means that the script will be placed in the “hello_world” directory, which is located in the same location as the main template file.
The Handler property is a parameter that specifies the actual function to be executed when the Lambda function is called. By specifying “app.lambda_handler”, it means that the lambda_handler function in the app.py file located in the “hello_world” directory will be executed.
The Runtime property is a parameter that specifies the runtime environment for the function. In this case, we will specify Python 3.8 to run the function.
The Events property allows you to define the events associated with this function.
Specifies the events that trigger this function. Events consist of a type and a set of properties that depend on the type.
AWS::Serverless::Function
This time, we will use this property to define the API Gateway associated with this function.
You can specify the resource to be created in the Type property in the Events property.
Object describing properties of this event mapping. The set of properties must conform to the defined Type.
Type: S3|SNS|Kinesis|DynamoDB|SQS|Api|Schedule|CloudWatchEvent|EventBridgeRule|CloudWatchLogs|IoTRule|AlexaSkill|Cognito|HttpApi|MSK|MQ
EventSource
Since we will be creating an HTTP API type API Gateway, specify “HttpApi”.
Specify the various parameters of the resource to be created in the Properties property.
The Path and Method properties are parameters related to the API Gateway root. In this case, we will specify that this function will be executed when “/hello”, the endpoint to be created, is accessed by GET.
The content of the function to be executed is the same as in Serverless apps using Lambda and API Gateway, so please check there.
SAM Application Deployment
Build and deploy with AWS SAM CLI.
First, let’s build.
$ sam build --use-container
Starting Build inside a container
Building codeuri: hello_world/ runtime: python3.8 metadata: {} functions: ['HelloWorldFunction']
Fetching amazon/aws-sam-cli-build-image-python3.8 Docker container image...................................................................................................................................................................................................................................................................
Mounting /your-directory/hello_world as /tmp/samcli/source:ro,delegated inside runtime container
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Invoke Function: sam local invoke
[*] Deploy: sam deploy --guided
Running PythonPipBuilder:ResolveDependencies
Running PythonPipBuilder:CopySource
Code language: Bash (bash)By using the use-container option, you can build your application in a dedicated Docker container.
If your functions depend on packages that have natively compiled dependencies, use this option to build your function inside a Lambda-like Docker container.
sam build
In this case, since we are using Python 3.8 as the runtime environment, the same environment must be available locally to run the CLI. However, by using this option, the build is completed in the container, so there is no need to worry about the local environment.
Next, we will proceed to deploy the application.
$ sam deploy --guided
Configuring SAM deploy
======================
Looking for config file [samconfig.toml] : Not found
Setting default arguments for 'sam deploy'
=========================================
Stack Name [sam-app]: fa-006
AWS Region [us-east-1]: ap-northeast-1
#Shows you resources changes to be deployed and require a 'Y' to initiate deploy
Confirm changes before deploy [y/N]: y
#SAM needs permission to be able to create roles to connect to the resources in your template
Allow SAM CLI IAM role creation [Y/n]: y
HelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y
Save arguments to configuration file [Y/n]: y
SAM configuration file [samconfig.toml]:
SAM configuration environment [default]:
....
Deploying with following values
===============================
Stack name : fa-006
Region : ap-northeast-1
Confirm changeset : True
Deployment s3 bucket : [bucket-name]
Capabilities : ["CAPABILITY_IAM"]
Parameter overrides : {}
Signing Profiles : {}
Initiating deployment
=====================
HelloWorldFunction may not have authorization defined.
Waiting for changeset to be created..
CloudFormation stack changeset
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
Operation LogicalResourceId ResourceType Replacement
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
+ Add HelloWorldFunctionHelloWorldPermission AWS::Lambda::Permission N/A
+ Add HelloWorldFunctionRole AWS::IAM::Role N/A
+ Add HelloWorldFunction AWS::Lambda::Function N/A
+ Add ServerlessHttpApiApiGatewayDefaultStage AWS::ApiGatewayV2::Stage N/A
+ Add ServerlessHttpApi AWS::ApiGatewayV2::Api N/A
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
Changeset created successfully. arn:aws:cloudformation:ap-northeast-1:[accound-id]:changeSet/samcli-deploy1641285770/e5418e4b-792d-4e96-93ae-5d10a45ee858
Previewing CloudFormation changeset before deployment
======================================================
Deploy this changeset? [y/N]: y
...
CloudFormation outputs from deployed stack
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
Outputs
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
Key HelloWorldFunctionIamRole
Description Implicit IAM Role created for Hello World function
Value arn:aws:iam::[account-id]:role/fa-006-HelloWorldFunctionRole-VBT1AK5MRG5J
Key HelloWorldApi
Description API Gateway endpoint URL for Prod stage for Hello World function
Value https://25ypbm7one.execute-api.ap-northeast-1.amazonaws.com/hello
Key HelloWorldFunction
Description Hello World Lambda Function ARN
Value arn:aws:lambda:ap-northeast-1:[account-id]:function:fa-006-HelloWorldFunction-qajs4WIMSN60
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
Successfully created/updated stack - fa-006 in ap-northeast-1
Code language: Bash (bash)Deployment has been completed successfully.
From the deployment log, we can see that five resources have been created this time.
Also, from the output in the Outputs section, we can see that the API Gateway endpoint created this time is “https://25ypbm7one.execute-api.ap-northeast-1.amazonaws.com/hello”.
Access the SAM application
Now let’s actually access it.
https://25ypbm7one.execute-api.ap-northeast-1.amazonaws.com/hello
{"message": "hello world from Awstut !"}
Code language: Bash (bash)We were able to successfully retrieve the results of the Lambda function execution.
As you can see, by using SAM, we were able to build a serverless application more concisely than with the normal CloudFormation notation.
(Reference) Details of various resources created by SAM
We will check the status of various resources of the application deployed with SAM.
As we saw at the beginning, SAM is a variant of CloudFormation, so deploying a SAM application will create a CloudFormation stack.
Although not included in this stack, Route and Integration of API Gateway resources have also been created.
Check the status of the stack creation from the AWS Management Console.
Although not directly defined in the template file, you can see that the Permission for API Gateway to call the Lambda function and the IAM role to be granted to the Lambda function are also automatically created.
The contents of Permission are as follows.
The conditions for calling the Lambda function are defined. Only calls from the API Gateway created this time and from the GET method with the URL /hello will be allowed.
The following is the IAM role that has been created.
You can see that the AWS managed policy AWSLambdaBasicExecutionRole has been attached, which means that the minimum privileges for executing Lambda functions have been granted.
Although not included in this stack, API Gateway root and integration resources have also been created.
First is integration.
You can see that the Lambda function we created is associated with it.
Next is the route.
The GET method of /hello is associated with the previous integration. The combination of these settings will allow the Lambda function to be executed when the API Gateway is accessed.
Summary
We found that using SAM allows us to build serverless applications in a more concise manner compared to the usual CloudFormation notation.
