Kong Functions (Pre-Plugins)

Overview Get started Configuration reference Changelog

Phases

The Pre-Function plugin can run custom Lua code in any of the following phases in Kong Gateway’s lifecycle:

access
body_filter
certificate
header_filter
log
rewrite
ws_client_frame
ws_close
ws_handshake
ws_upstream_frame

To run the Pre-Function plugin in a specific phase, use a config.PHASE_NAME parameter. For example, to run the plugin in the header_filter phase, use config.header_filter.

You can also run the plugin in multiple phases. See Running Pre-Function in multiple phases for an example.

Passing Lua code to the plugin

Since Kong Gateway expects the Lua code in a string format, we recommend either uploading a file through the Admin API using the @file.lua syntax, or minifying your Lua code using a minifier.

The syntax for passing a file to the Pre-Function plugin depends on the tool you’re using.

decK doesn’t support the file syntax directly. If you want to pass Lua files to decK, you’ll need to use environment variables to include the content of your Lua script:

Create your Lua script and save it in a file, for example, function.lua.
Load the contents of the Lua script into an environment variable:
```
export DECK_FUNCTION=$(cat function.lua)
```

Reference the variable in a decK file:

plugins:
- name: pre-function
  config:
    access:
    - |
       ${{ env "DECK_FUNCTION" }}

If you’re using the Admin API or Konnect Control Plane Config API, you can pass each chunk of Lua code as a form parameter and a filename.

For example:

--form "config.access=@/tmp/access-serverless.lua"

Alternatively, you can pass the contents of the file into an environment variable:

export FUNCTION=$(cat function.lua)

Then pass the environment variable to the API:

--data "config.access=$FUNCTION"

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

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.

Kong Functions (Pre-Plugins)

Phases

Passing Lua code to the plugin

Upvalues

Sandboxing

Help us make these docs great!

Still need help