Serverless Functions

Dynamically run Lua code from Kong during access phase.

Terminology

• plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
• Service: the Kong entity representing an external upstream API or microservice.
• Route: the Kong entity representing a way to map downstream requests to upstream services.
• upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.
• API: a legacy entity used to represent your upstream services. Deprecated in favor of Services since CE 0.13.0 and EE 0.32.

Configuration

Enabling the plugin on a Service

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=serverless-functions"  \
    --data "config.functions=[]"

• service: the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=serverless-functions"  \
    --data "config.functions=[]"

• route_id: the id of the Route that this plugin configuration will target.

Enabling the plugin on an API

If you are using an older version of Kong with the legacy API entity (deprecated in favor of Services since CE 0.13.0 and EE 0.32.), you can configure this plugin on top of such an API by making the following request:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=serverless-functions"  \
    --data "config.functions=[]"

• api: either id or name of the API that this plugin configuration will target.

Global plugins

All plugins can be configured using the http://kong:8001/plugins/ endpoint. A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Plugin Names

Serverless Functions come as two separate plugins. Each one runs with a different priority in the plugin chain.

• pre-function
  • Runs before other plugins run during access phase.
• post-function
  • Runs after other plugins in the access phase.

Demonstration

1. Create a Service on Kong:

    $ curl -i -X  POST http://localhost:8001/services/ \
      --data "name=plugin-testing" \
      --data "url=http://httpbin.org/headers"
   
    HTTP/1.1 201 Created
    ...
   

2. Add a Route to the Service:

    $ curl -i -X  POST http://localhost:8001/services/plugin-testing/routes \
      --data "paths[]=/test"
   
    HTTP/1.1 201 Created
    ...
   

3. Create a file named custom-auth.lua with the following content:

    -- Get list of request headers
    local custom_auth = kong.request.get_header("x-custom-auth")
   
    -- Terminate request early if our custom authentication header
    -- does not exist
    if not custom_auth then
      return kong.response.exit(401\, "Invalid Credentials")
    end
   
    -- Remove custom authentication header from request
    kong.service.request.clear_header('x-custom-auth')
   

4. Ensure the file contents:

    $ cat custom-auth.lua
   

5. Apply our Lua code using the pre-function plugin using cURL file upload:

    $ curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \
        -F "name=pre-function" \
        -F "config.functions=@custom-auth.lua"
   
    HTTP/1.1 201 Created
    ...
   

6. Test that our Lua code will terminate the request when no header is passed:

    curl -i -X GET http://localhost:8000/test
   
    HTTP/1.1 401 Unauthorized
    ...
    "Invalid Credentials"
   

7. Test the Lua code we just applied by making a valid request:

    curl -i -X GET http://localhost:8000/test \
      --header "x-custom-auth: demo"
   
    HTTP/1.1 200 OK
    ...
   

This is just a small demonstration of the power these plugins grant. We were able to dynamically inject Lua code into the plugin access phase to dynamically terminate, or transform the request without creating a custom plugin or reloading / redeploying Kong.

In short, serverless functions give you the full capabilities of a custom plugin in the access phase without ever redeploying / restarting Kong.

Notes

Fake Upstreams

Since the Service entity requires defining an upstream you may define a fake upstream and take care to terminate the request. See the lua-ngx-module documentation for more information.

Escaping Commas

Since the Lua code blocks are sent in an Array, when using form-data you might run into an issue with code being split when using commas. To avoid this situation escape commas using the backslash character \,.

Minifying Lua

Since we send our code over in a string format, it is advisable to use either curl file upload @file.lua (see demonstration) or to minify your Lua code using a minifier.