Kong Functions (Pre-Plugins) - unreleased

You are browsing unreleased documentation.

Looking for the plugin's configuration parameters? You can find them in the Kong Functions (Pre-Plugins) configuration reference doc.

The Pre-function plugin (otherwise known as Kong Functions, Pre-Plugin) lets you dynamically run Lua code from Kong, before other plugins in each phase.

The plugin can be applied to individual services, routes, or globally.

This plugin is part of a pair of serverless plugins. If you need to run Lua code after other plugins in each phase, see the Post-function plugin.

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

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.* (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.
The kong.cache points to a cache instance that is dedicated to the Serverless Functions plugins. It does not provide access to the global Kong Gateway cache. It only exposes the get method. Explicit write operations like set or invalidate are not available.

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.

Get started with Pre-functions

Next Kong Functions (Pre-Plugins) Configuration