Skip to content
Kong Gateway 2.8 Increases Security and Simplifies API Management.  —Learn More →
|
search
Plugin Hub
header icon

Serverless Functions

Dynamically run Lua code from Kong.

The Serverless Functions plugin comes 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. The pre-function plugin can only run globally. It can’t be applied to individual services, routes, or consumers.
  • post-function
    • Runs after other plugins in each phase. The post-function plugin can be applied to individual services, routes, consumers, or globally.
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

This plugin is partially compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

  • Setting a target's health status in the load balancer
  • Validating configurations against schemas
  • Uploading the declarative configuration using the /config endpoint

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

Parameters

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

Form Parameter Description
name
required

Type: string		 The name of the plugin, 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
required

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.

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

  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"

    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.

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

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

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

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

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

    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

Sandboxing

Starting with version 2.0 of the plugin, the provided Lua environment is sandboxed.

Sandboxing consists of several limitations in the way the Lua code can be executed, for heightened security.

The following functions are not available because they can be used to abuse the system:

  • string.rep: Can be used to allocate millions of bytes in one operation.
  • {set|get}metatable: Can be used to modify the metatables of global objects (strings, numbers).
  • collectgarbage: Can be abused to kill the performance of other workers.
  • _G: Is the root node which has access to all functions. It is masked by a temporary table.
  • load{file|string}: Is deemed unsafe because it can grant access to the global environment.
  • raw{get|set|equal}: Potentially unsafe because sandboxing relies on some metatable manipulation.
  • string.dump: Can display confidential server information (such as implementation of functions).
  • math.randomseed: Can affect the host system. Kong Gateway already seeds the random number generator properly.
  • All os.* (except os.clock, os.difftime, and os.time). os.execute can significantly alter the host system.
  • io.*: Provides access to the hard drive.
  • dofile|require: Provides access to the hard drive.

The exclusion of require means that plugins must only use PDK functions kong.*. The ngx.* abstraction is also available, but it is not guaranteed to be present in future versions of the plugin.

In addition to the above restrictions:

  • All the provided modules (like string or table) are read-only and can’t be modified.
  • Bytecode execution is disabled.

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.