Serverless Functions plugin

Dynamically run Lua code from Kong.

Warning: The pre-function and post-function serverless plugin allows anyone who can enable the plugin to execute arbitrary code. If your organization has security concerns about this, disable the plugin in your kong.conf file.

Configuration Reference

You can configure this plugin using the Kong Admin API or through declarative configuration, which involves directly editing the Kong configuration file.

This plugin is compatible with requests with the following protocols:

http
https

This plugin is partially compatible with DB-less mode.

In DB-less mode, Kong does not have an Admin API. If using this mode, configure the plugin using declarative configuration.

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

Kong Admin API

Kubernetes

Declarative (YAML)

For example, configure this plugin on a Service by making the following request:

$ curl -X POST http://<admin-hostname>:8001/services/<service>/plugins \
    --data "name=pre-function OR post-function"  \
    --data "config.functions=[]" \
    --data "config.certificate=[]" \
    --data "config.rewrite=[]" \
    --data "config.access=[]" \
    --data "config.header_filter=[]" \
    --data "config.body_filter=[]" \
    --data "config.log=[]"

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <pre-function OR post-function-example>
config: 
  functions: []
  certificate: []
  rewrite: []
  access: []
  header_filter: []
  body_filter: []
  log: []
plugin: pre-function OR post-function

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

apiVersion: v1
kind: Service
metadata:
  name: <service>
  labels:
    app: <service>
  annotations:
    konghq.com/plugins: <pre-function OR post-function-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: <service>
  selector:
    app: <service>

Note: The KongPlugin resource only needs to be defined once and can be applied to any Service, Consumer, or Route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a Service by adding this section to your declarative configuration file:

plugins:
- name: pre-function OR post-function
  service: <service>
  config: 
    functions: []
    certificate: []
    rewrite: []
    access: []
    header_filter: []
    body_filter: []
    log: []

<service> is the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

Kong Admin API

Kubernetes

Declarative (YAML)

For example, configure this plugin on a Route with:

$ curl -X POST http://<admin-hostname>:8001/routes/<route>/plugins \
    --data "name=pre-function OR post-function"  \
    --data "config.functions=[]" \
    --data "config.certificate=[]" \
    --data "config.rewrite=[]" \
    --data "config.access=[]" \
    --data "config.header_filter=[]" \
    --data "config.body_filter=[]" \
    --data "config.log=[]"

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <pre-function OR post-function-example>
config: 
  functions: []
  certificate: []
  rewrite: []
  access: []
  header_filter: []
  body_filter: []
  log: []
plugin: pre-function OR post-function

Then, apply it to an ingress (Route or Routes) by annotating the ingress as follows:

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: <route>
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <pre-function OR post-function-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

For example, configure this plugin on a Route by adding this section to your declarative configuration file:

plugins:
- name: pre-function OR post-function
  route: <route>
  config: 
    functions: []
    certificate: []
    rewrite: []
    access: []
    header_filter: []
    body_filter: []
    log: []

<route> is the id or name of the Route that this plugin configuration will target.

Enabling the plugin globally

A plugin which is not associated to any Service, Route, or Consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Kong Admin API

Kubernetes

Declarative (YAML)

For example, configure this plugin globally with:

$ curl -X POST http://<admin-hostname>:8001/plugins/ \
    --data "name=pre-function OR post-function"  \
    --data "config.functions=[]" \
    --data "config.certificate=[]" \
    --data "config.rewrite=[]" \
    --data "config.access=[]" \
    --data "config.header_filter=[]" \
    --data "config.body_filter=[]" \
    --data "config.log=[]"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-pre-function OR post-function>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  functions: []
  certificate: []
  rewrite: []
  access: []
  header_filter: []
  body_filter: []
  log: []
plugin: pre-function OR post-function

For example, configure this plugin using the plugins: entry in the declarative configuration file:

plugins:
- name: pre-function OR post-function
  config: 
    functions: []
    certificate: []
    rewrite: []
    access: []
    header_filter: []
    body_filter: []
    log: []

Parameters

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

Form Parameter	Description
`name` Type: string	The name of the plugin to use, in this case `pre-function OR post-function`.
`service.id` Type: string	The ID of the Service the plugin targets.
`route.id` Type: string	The ID of the Route the plugin targets.
`enabled` Type: boolean Default value: `true`	Whether this plugin will be applied.
`config.functions` optional Default value: []	Deprecated; use `config.access` instead. Array of stringified Lua code to be cached and run in sequence during access phase.
`config.certificate` optional Default value: []	Array of stringified Lua code to be cached and run in sequence during the certificate phase. Note: This only runs on global plugins.
`config.rewrite` optional Default value: []	Array of stringified Lua code to be cached and run in sequence during the rewrite phase. Note: This only runs on global plugins.
`config.access` optional Default value: []	Array of stringified Lua code to be cached and run in sequence during the access phase.
`config.header_filter` optional Default value: []	Array of stringified Lua code to be cached and run in sequence during the header_filter phase.
`config.body_filter` optional Default value: []	Array of stringified Lua code to be cached and run in sequence during the body_filter phase.
`config.log` optional Default value: []	Array of stringified Lua code to be cached and run in sequence during the log phase.

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 each phase.
post-function
- Runs after other plugins in each phase.

Demonstration

With a database

Without a database

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

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

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')

Ensure the file contents:
```
 $ cat custom-auth.lua
```

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.access[1]=@custom-auth.lua" \
     -F "config.access[2]=kong.log.err('Hi there Access!')" \
     -F "config.header_filter[1]=kong.log.err('Hi there Header_Filter!')" \
     -F "config.body_filter[1]=kong.log.err('Hi there Body_Filter!')" \
     -F "config.log[1]=kong.log.err('Hi there Log!')"

 HTTP/1.1 201 Created
 ...

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"
```
In the logs, there will be the following messages:
```
 [pre-function] Hi there Header_Filter!
 [pre-function] Hi there Body_Filter!
 [pre-function] Hi there Body_Filter!
 [pre-function] Hi there Log!
```
The “Access” message is missing because the first function in that phase does an early exit, throwing the 401. Hence the subsequent functions are not executed.

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

Now the logs will also have the “Access” message.

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:
     access:
     - |2
         -- Get list of request headers
         local custom_auth = kong.request.get_header("x-custom-auth")

         -- Terminate request early if the 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')
     - kong.log.err('Hi there Access!')
     header_filter:
     - kong.log.err('Hi there Header_Filter!')
     body_filter:
     - kong.log.err('Hi there Body_Filter!')
     log:
     - kong.log.err('Hi there Log!')

Test that the 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"
```
The following messages will be in the logs:
```
 [pre-function] Hi there Header_Filter!
 [pre-function] Hi there Body_Filter!
 [pre-function] Hi there Body_Filter!
 [pre-function] Hi there Log!
```
The “Access” message is missing because the first function in that phase does an early exit, throwing the 401. Hence the subsequent functions are not executed.

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

Now the logs will also have the “Access” message.

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

In summary, serverless functions give you the full capabilities of a custom plugin without requiring redeploying or 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 you can return a function to run on each request, allowing for upvalues to keep state in between requests:

-- this runs once on the first request
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.

About this Plugin
Made by
Categories	Serverless
DB-less compatible?	Partially (Kong Gateway only)
Source	Code
Bundled with...
Kong Enterprise 2.2.x 2.1.x 1.5.x Kong Community 2.2.x 2.1.x