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.

Configuration

This plugin is compatible with requests with the following protocols:

• http
• https

This plugin is partially compatible with DB-less mode.

The functions will be executed, but if the configured functions attempt to write to the database, the writes will fail.

Enabling the plugin on a Service

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

plugins:
- name: pre-function OR post-function
  service: {service}
  config: 
    functions: []

{service} is the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

$ curl -X POST http://kong:8001/routes/{route}/plugins \
    --data "name=pre-function OR post-function"  \
    --data "config.functions=[]"

plugins:
- name: pre-function OR post-function
  route: {route}
  config: 
    functions: []

{route} is the id or name of the Route that this plugin configuration will target.

Global plugins

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.

• Using a database, all plugins can be configured using the http://kong:8001/plugins/ endpoint.
• Without a database, all plugins can be configured via the plugins: entry on the declarative configuration file.

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

With a Database

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
    ...
   

Without a Database

1. Create the Service, Route and Associated plugin on the declarative config file:

    services:
    - name: plugin-testing
      url: http://httpbin.org/headers
   
    routes:
    - service: plugin-testing
      paths: [ "/test" ]
   
    plugins:
    - name: pre-function
      config:
        functions: |
          -- 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')
   

2. 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"
   

3. 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

Upvalues

Prior to version 0.3 of the plugin, the provided Lua code would run as the function. From version 0.3 onwards also a function can be returned, to allow for upvalues.

So the older version would do this (still works with 0.3 and above):

-- this entire block is executed on each request
ngx.log(ngx.ERR, "hello world")

With this version version you can return a function to run on each request, allowing for upvalues to keep state in between requests:

-- this runs once when Kong starts
local count = 0

return function()
  -- this runs on each request
  count = count + 1
  ngx.log(ngx.ERR, "hello world: ", count)
end

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.