I have recently been working on a plugin for the Serverless Framework, which aims to configure the RouteSettings for your HTTP Api Gateway v2 stages. Just wanted to share some notes about the plugin and the odd bit that I learnt throughout the process.

Learn More: Serverless.com

Github: Github

Download: npm

What is the plugin for?

This is the CloudFormation Object for ApiGateway v2 Stage RouteSettings, which is what the plugin aims to configure:

{
  "DataTraceEnabled" : Boolean,
  "DetailedMetricsEnabled" : Boolean,
  "LoggingLevel" : String,
  "ThrottlingBurstLimit" : Integer,
  "ThrottlingRateLimit" : Double
}

As of right now the plugin supports:

  • DetailedMetricsEnabled
  • ThrottlingBurstLimit
  • ThrottlingBurstLimit

as DataTraceEnabled and LoggingLevel only work for WebSocket API’s. Maybe I will add support one day for Websocket API’s. 🙂

How can I install the plugin?

At the root of your serverless project:

npm install serverless-apigateway-route-settings

or

yarn add serverless-apigateway-route-settings

How do I configure the plugin?

Let serverless know that you’re using the plugin with the following:

plugins:
  - serverless-apigateway-route-settings

Next, edit your serverless.yml for DefaultRouteSettings. What you enter here will be the default for each route in the stage.

custom:
  routeSettings:
    burstLimit: 200
    rateLimit: 400
    detailedMetricsEnabled: true

You can override the default route settings/account defaults by configuring at the function/route level. for example:

functions:
  # Inherits the default throttle rate limits.
  hello:
    handler: src/throttle_me.handler
    events:
      - httpApi:
          path: /hello
          method: GET
          routeSettings:
            rateLimit: 10
            burstLimit: 5
            detailedMetricsEnabled: false

What will be added to your CloudFormation template?

  • DefaultRouteSettings will be added to your Stage.
  • RouteSettings will be added to your Stage.
  • The DependsOn attribute is edited for your Stage. We simply add any Route’s with configured RouteSettings, to ensure the creation of the Routes before the Stage. Otherwise CloudFormation will error (as it tries to edit the RouteSettings for a Route that doesn’t exist yet).

Caveats

  • Currently, if we are to deploy with default route settings specified, then remove them, they will persist, you MUST specify new default route settings. I aim to fix this in an update, will default to account levels.
  • Doesn’t work with pre existing API Gateways, eg if they are existing and we simply add routes in the serverless.yml. It is possible to add this plugin to an existing api gateway which is handled by serverless however.

Example serverless.yml

service: example

frameworkVersion: '2'

plugins:
  - serverless-apigateway-route-settings

custom: 
  routeSettings:
    detailedMetricsEnabled: true
    rateLimit: 200
    burstLimit: 30

provider:
  name: aws
  runtime: nodejs12.x

functions:
  # Inherits the default route settings.
  hello:
    handler: src/helloWorld.handler
    events:
      - httpApi:
          path: /hello
          method: GET
          routeSettings:
            detailedMetricsEnabled: false

  # Overrides the default throttle rate limits.
  lowerRateLimit:
    handler: src/lowerRateLimit.handler
    events:
      - httpApi:
          path: /throttle
          method: GET
          routeSettings:
            rateLimit: 10
            burstLimit: 3