Serverless Study

Reference

https://aws.amazon.com/getting-started/serverless-web-app/

https://serverless.com/

Example Study: API Gateway, Swagger, Lambda, DynamoDB

https://cloudonaut.io/create-a-serverless-restful-api-with-api-gateway-swagger-lambda-and-dynamodb/

Cloudformation creates everything except for API Gateway, Swagger with API Gateway extension creates API Gateway, that maps operation with parameters (kind of smart move). Model - defined in Swagger. although example did not enable verify body, can be enabled with just one click. And the verification is done by cloudfront.

Swagger is replaced by OpenAPI, so bit out dated. Also involve multiple steps with cloudformation stack update. Not the best choice.

Example Study: API Gateway, Serverless Framework, Lambda, DynamoDB

https://cloudonaut.io/create-a-serverless-restful-api-with-the-serverless-framework-powered-by-api-gateway-lambda-and-dynamodb/

Serverless framework seems make things easy but it's not AWS native. Why should I learn one more thing which is not native?

Example Study: API Gateway, Lambda, DynamoDB

https://cloudonaut.io/create-a-serverless-restful-api-with-api-gateway-cloudformation-lambda-and-dynamodb/

Native. Everything from cloudformation. Should study this one.

Descriptor / Tools

AWS Serverless Application Model (AWS SAM)

Simplified template to define serverless applications. Translate to CloudFormation (if a stack is deployed with SAM, can find the translated cloudformation template on console). Only a subset of CF template, only deals with (as of July 2018) lambda, API Gateway, cognito, DynamoDB, etc.

SAM Local is a tool to (1) initialize serverless application project (2) debug lambda locally (3) uses SAM model definition (4) but as to July 2018 only deals with lambda and ignore other resources. (5) package - but cannot specify name, and deploy, by calling "aws cloudformation deploy", first upload to s3

SAM can be used with swagger together to define Api. However, in that case,

• in sam template, definition location (DefinitionBody: 'Fn::Transform': ... Parameters: Location:) must be specified as a valid s3 url (the swagger file must be uploaded), cannot just pack the swagger file in the package, that does not work
• even the template can be successfully deployed, "sam validate" won't pass and does not return meaningful message other than just "not a valid template"
• In "CodeUri" of LambdaFunction properties, should just put "." indicating current directory. Some example uses a S3 url and that does not work.

CloudFormation template (according to this discussion) works great and give complete power, however may be overwhelming to beginners. SAML with examples leads user to resources needed.

Serverless Framework seems also has a way to define serverless application, and far less verbose than SAM (see discussion here). Still not so sure about it. Another comparison (https://sanderknape.com/2018/02/comparing-aws-sam-with-serverless-framework/) seems suggest SAM better than Serverless Framework. There is a project "serverless-sam" to convert serverless template to SAM template.

Swagger (OpenAPI Specification) "defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service ... a consumer can understand and interact with the remote service with a minimal amount of implementation logic."; there are lots of tools (tooling ecosystem) surrounding the specification. Swagger can be used to create API Gateway for REST API. SAM can use Swagger to describe AWS::Serverless::Api (otherwise SAM can use Events in AWS::Serverless::Function to implicitly define API). CloudFormation also can use Swagger to create API Gateway for REST API. However at this moment (July 2018) Swagger cannot generate client for OpenAPI 3.0, and CloudFormation still only accept swagger 2.0.

The SAM Way

Project scaffolding:

• `sam init` to initiate the structure
• `cd sam-app; npm init` to initiate the package

Cloudformation template:

• use SAM template for simplicity on certain resources
• can still write cloudformation resources into the template
• for ease of management and drafting, can separate the file into multiple parts and assemble up - the easiest way to do this is to just use a shell script

API-Gateway swagger files:

• Easiest way to define API Gateway is (1) use console to build and test the gateway (2) deploy (3) export the swagger + extension file from stage (4) remove "host" and change the hard coded strings, such as resource Arns, into references such as "Fn::GetAtt": ["ResourceLogicName", "Arn"]

Dynamodb Tables:

• If table name specified, table name is fixed but this resource cannot be updated. Solution (only) is rename the table name in template and do update. This creates a new table and keeps the old one. DO NOT manually delete the existing table and expect cloudformation would create a new one. It does not work this way. Doing this will result the stack in an invalid state.
• Initialization is possible with custom resource (lambda)
• It's easier just work with the cloud tables. No need to start a local dynamodb instance. (it would be faster, though, but would need to write script to create table and change end point in code, not worth the effort)

Lambda

• First use `sam local generate-event` to generate an event
• Specify the resource 'AWS::Serverless::Function' in template and write an empty handler function
  • Specify a time out
  • Empower it with some policies
  • Can pass reference to other resources & parameters from environment variable
  • It actually does NOT need an Event section, since the Api Gateway swagger + extension document does just that.
• Deploy the resources to see if it works
• Add debug launch option in Visual Studio Code, just to attach to a debug port; write script to test function `sam local invoke...`
• Write-debug the code in interactive style, until satisfy
• Note the returned result, for Api-Gateway Lambda Proxy mode, the result must be an object with required attributes such as http response code, headers, etc.
• CORS - to enable, also need the required header in response code
• The function can be normal function or async function. Async function is preferred.

Api-Gateway / Lambda proxy:

• After lambda is tested locally, deploy to cloud
  • Give the lambda sufficient privileges in "Policy" section or give it an appropriate role. When testing locally, local credential is used which is usually powerful enough. When deploying to cloud, the policies / roles in the template defines what privileges the lambda function has.
• Create the Api-Gateway / resource with console
  • Create the resource (path)
  • Create method
  • Action - enable CORS: note this is not a "turn on/off" setting, but a tool to create CORS settings. So this should be done repeatedly after change to the resource & method (like adding a method). What's done exactly? (1) add/update OPTIONS method to return the CORS response with a mock-up (2) add headers in other method (GET,POST) "Method Response" (3) also note the setting only add the header, not the header content. Header content is to be returned object from the Lambda.
  • The 4 parts of the method, "Method Request": can set Authorization & Request validator here, "Integrated request": integration type Lambda Function, check "Use Lambda Proxy integration" to make request details available in "event" object received by lambda handler. This is the most easiest but also not much to config. "Integration Response" cannot be set under Lambda Proxy integration. "Method Response" has not much to set, Response Header for a response code is added by CORS. Otherwise not much to set.
  • Don't forget to deploy
  • Test
  • If everything works, create the Api-Gateway resource in template, export the swagger + extension document, remove hard coded 'host' and replace the hard coded resource reference, do a stack update.
  • Commit and push source!
  • Front-end - usually it's sufficient to just use axios, without the generated API