Serverless Framework allows to build serverless apps on AWS using Lambda, API Gateway and S3. In this tutorial you’ll learn the basics to start using the Serverless Framework.

Table of Contents

Installation

You can install Serverless Framework tools with npm (Node).

npm install -g serverless

Initial configuration

First you need to specify your AWS credentials (access keys). There are several ways to do this:

  • If AWS CLI is installed on your system (and configured with credentials after running aws configure), you don’t need to do anything, because Serverless will get the credentials from $HOME/.aws.
  • You can also specify the credentials with serverless config credentials: 
    serverless config credentials --provider aws --key <aws_access_key_id> --secret <aws_secret_access_key>

After that, run serverless and follow the prompts to create a new Serverless project on your working directory (Serverless will create a new folder for the project).

serverless.yml

Basic structure

This is the main file for a Serverless project: here you will define all functions, events, roles, etc. We are going to analyze the file syntax (line identation is important, be consistent using tabs or spaces):

service: my-project
  • First, specify the project name with the service property.
frameworkVersion: '3'
  • Define the Framework version you are using. Run serverless --version if you are unsure. Check Framework Core version number (e.g.: 3.22.0) and type only the first number (3 in this case).
provider:
  • Under provider section there are several properties:
    • name: aws.
    • runtime: <runtime>: specify the runtime your functions will use.
    • lambdaHashingVersion: 20201221.
    • stage: prod.
    • region: <region>. type the region where the functions will reside.
    • iam: here you will specify the IAM roles, for example: ``` iam: role: statements:
      • Effect: Allow Action:
        • ‘s3:’ Resource: ‘arn:aws:s3:::mybucket/’ ```
      • Inside statements: you type the IAM roles: the effect (Allow, Deny), the action and the resource (use the ARN for the resouce).
  • functions: here you define your function name, memory size, events, etc,
    • myfunction: first, type your function name (replace myfunction). Inside this parameter, there are some properties:
      • handler: <handler method path>: type the path (relative to ‘serverless.yml’) to the function ‘exports.handler’ method (e.g.: lambda/myfunction/index.handler).
      • memorySize: <number>: type the memory size, in megabytes (e.g.: 128).
      • timeout: <seconds>: add a timeout in seconds (e.g.: 5).
      • events:: here you define the events that trigger the function.
        • httpApi:: create an API listener, with a path and a HTTP method (get, post, etc.)
          • path: /myfunction
          • method: post

This is an example of a complete ‘serverless.yml’ file:

service: my-project

frameworkVersion: '3'

provider:
  name: aws
  runtime: nodejs16.x
  lambdaHashingVersion: 20201221
  stage: prod
  region: eu-west-1
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - 's3:*'
          Resource: 'arn:aws:s3:::my-bucket/*'

functions:
  login:
    handler: lambda/login/index.handler
    memorySize: 128
    timeout: 10
    events:
      - httpApi:
          path: /login
          method: post

Advanced tips

Tags

You can add a tag for all the assets of your project, this property go inside provider section:

tags:
    project: my-tag
  • If you use an API and you want to tag it as well, add (after project: line): 
    httpApi:
useProviderTags: true

Roles

Grant getItem permission to a DynamoDB table:

- Effect: Allow
  Action:
  - 'dynamodb:getItem'
  Resource: 'arn:aws:dynamodb:eu-west-1:12345678:tablemy-table'

Events

Add an S3 event:

- s3:
  bucket: my-bucket
  event: s3:ObjectCreated:*
  rules:
  - prefix: path/to/folder/
  existing: true
  • The rules property is optional, use it when you want to limit the event to some folder path.
  • existing: true means the bucket already exists.

Add a DynamoDB stream event:

- stream:
    type: dynamodb
    arn: 'arn:aws:dynamodb:eu-west-1:12345678:table/my-table/stream/2022-01-01T18:26:33.939'

Layers

Inside the function section, you can specify Lambda layers the function will use (type their ARN):

layers:
  - arn:aws:lambda:eu-west-1:12345678:layer:my-layer:1

On the Web there are a lot of resources about how to create or import Lambda layers (using AWS Serverless Application Repository or manually) but this is an example of adding a useful Node package (‘sharp’) as a layer:

  • On a empty folder called nodejs, install the desired NPM package: 
    npm install sharp
  • Create a ZIP file of the ‘nodejs’ folder. The compressed file need to have this structure: 
    nodejs/
  node_modules/
  package-lock.json
  package.json
  • You can optionally upload the file to S3 (this is the recommended practice if the file is bigger than 30MB).
  • Go to AWS page, Lambda -> Layers and create a new layer. Upload the file or check Upload from S3 and paste the S3 URL.
  • Define a recommended architecture (optional) and runtime and click on Create layer.
  • Copy the layer ARN (version number included) and paste it on your ‘serverless.yml’.

Deploy your project

To deploy (and update) a project, run:

serverless deploy

When the process finishes, you’ll see the resources created (also the API URL).

Update a function configuration

To update a function configuration (or its content), run:

serverless deploy function --function <function name>

If you have any suggestion, feel free to contact me via social media or email.