Deploy a Koop app to AWS Lambda

AWS Lambda is a serverless compute service offered by Amazon Web Service that comes with

  • free usage of 1 million requests per month
  • fully managed server with auto scaling
  • easy integration with other AWS services

These features make the AWS Lambda very suitable for hosting a Koop application with little cost or limitted management resources. Use cases can include

  • A free experiemental ETL service that only serves a small amount traffic
  • A data service that handles very dynmac requests in events like natural disaster
  • A data service built on the existing AWS infrastructure

This guide will discuss how to deploy a Koop application to AWS Lambda and expose the APIs using AWS API Gateway. Since a Koop application is essentially an Expressjs server, this guide utilize the serverless framework and its serverless-http plugin to manage the deployment.

Serverless framework

The serverless framework is a CLI tool to manage the development and deployment of appliaction to cloud services, including AWS. It uses the configuration-as-code approach and stores the configuration in YAML format.

config-example

The framework also has a rich plugin ecosystem to cover the full lifecycle of the application development. Despite the framework’s core capability of AWS Lambda deployment, the serverless-http plugin is capable of wrapping a server into serverless APIs and creating endpoints at API Gateway.

Preparation

An AWS credential with privileges is required for the deployment process:

  • read/write S3
  • manage Lambda
  • manage API Gateway

Code update

This guide is based on the Koop application created by the Koop CLI. It needs a few updates on the code generated by the CLI.

Installing dependencies

First the serverless framework can be installed into the project:

npm install serverless serverless-http serverless-offline

and create a command in the package.json file

{
  "scripts": {
    "deploy": "sls deploy",
    "start": "sls offline start"
  }
}

The serverless framework documentation provides a guide on how to setup the credential for the CLI. See this link for details.

Creating lambda function handlers

Instead of running the Koop server, the project should export the lambda function handlers in the src/index.js file.

const Koop = require("koop");
const serverless = require("serverless-http");

// initiate a Koop app
const koop = new Koop();

// configure the Koop app

// NOTE: this line is the real change
// wrap the Koop server with the serverless framework
module.exports.handler = serverless(koop.server);

Creating serverless configuration

The Lambda function is configured with the file servless.yml in the project’s root directory.

The following example configuration shows how to set up a HTTP service exposing a Feature Service endpoint from a Koop application. All endpoints and parameteres in use should be explicitely defined in the configuration so that they can be properly created in API Gateway.

# Lambda function service name
service: koop-serverless-example

provider:
  name: aws
  runtime: nodejs10.x

functions:
  # The Koop-app lambda function handles HTTP requests
  koop-app:
    handler: src/index.handler
    events:
      # The "http" event defines an API at the API Gateway
      - http:
          path: /my-provider/{id}/FeatureServer/0
          method: get
          request:
            # Each parameter and query string need to be explicitly specified
            parameters:
              paths:
                id: true

You can start working on your configuration by updating and adding HTTP events in the example.

For details and options, check the Serverless AWS Guide.

Development and deployment

Once the framework and the code is done, testing and deployment the lambda functions is just a few commands.

The start command runs a local instance of the lambda function and expose the endpoint. It is completely the same as the clould version.

npm run start

The deploy command runs the fully automatic deployment to the cloud service.

npm run deploy

Beyond these two basic commands, the serverless framework provides a variety of CLI commands to manage the project. See the documentation for details.

Putting together

In summary, a few steps are needed to deploy your Koop application on the AWS Lambda:

  • Prepare an AWS credential
  • Install the serverless framework and setup your credential
  • Update Koop code to export the function handler
  • Create the serverless configuration
  • Read to deploy!

The koop-serverless-example repo provides a fully functional example to demonstrate the above content. You can try to deploy the example and learn how to modify your application for AWS Lambda.


Improve this page