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 be applied to individual services, routes, or globally.
- Runs before other plugins run during each phase. The
post-function
- Runs after other plugins in each phase. The
post-function
plugin can be applied to individual services, routes, or globally.
- Runs after other plugins in each phase. The
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.name or service.id
Type: string |
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
Type: string |
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
enabled
Type: boolean Default value: true |
Whether this plugin will be applied. |
config.certificate
optional Type: array 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 Type: array 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 Type: array Default value: []
|
Array of stringified Lua code to be cached and run in sequence during the access phase. |
config.header_filter
optional Type: array Default value: []
|
Array of stringified Lua code to be cached and run in sequence during the header_filter phase. |
config.body_filter
optional Type: array Default value: []
|
Array of stringified Lua code to be cached and run in sequence during the body_filter phase. |
config.log
optional Type: array Default value: []
|
Array of stringified Lua code to be cached and run in sequence during the log phase. |
Usage
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.
Sandboxing
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.*
(exceptos.clock
,os.difftime
, andos.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
ortable
) are read-only and can’t be modified. - Bytecode execution is disabled.
Upvalues
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.
Changelog
Kong Gateway 3.0
- The deprecated
config.functions
parameter has been removed from the plugin. Useconfig.access
instead. - The pre-function plugin changed priority from
+inf
to1000000
.
Kong Gateway 2.3
-
Introduced sandboxing, which is enabled by default. Only the Kong PDK, OpenResty
ngx
APIs, and Lua standard libraries are allowed. To change the default setting, see the Kong configuration property reference.This change was also introduced into previous releases through patch versions: 1.5.0.9, 2.1.4.3, and 2.2.1.0.