Kong Functions (Pre-Plugins) Policy

The Pre-Function Policy lets you dynamically run Lua code from AI Gateway before other Policies run in each phase.

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

Warning: The Pre-Function and Post-Function Policies allow anyone who can create the Policy to execute arbitrary code. If your organization has security concerns about this, disable the Policies in your kong.conf file.

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

• access
• body_filter
• certificate
• header_filter
• log
• rewrite
• ws_client_frame
• ws_close
• ws_handshake
• ws_upstream_frame

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

You can also run the Policy in multiple phases at once by setting more than one phase parameter in config.

AI Gateway expects Lua code in a string format. For a short script, write it directly in the Policy’s config:

ai_gateway_policies:
  - ref: pre-function
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Pre-Function - Inline Script
    name: pre-function
    type: pre-function
    config:
      access:
      - 'kong.log.info("hello world")
           '

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.

For a longer script, save it to a file and load it into an environment variable:

export FUNCTION_LUA=$(cat function.lua)

Then reference the environment variable in your Pre-Function Policy configuration:

ai_gateway_policies:
  - ref: pre-function
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Pre-Function - Script From File
    name: pre-function
    type: pre-function
    config:
      access:
      - !env FUNCTION_LUA

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.

You can return a function to run on each request, allowing for upvalues to keep state 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

The provided Lua environment is sandboxed.

Sandboxing imposes several limitations on how custom Lua code can be executed, for heightened security. The Lua (or LuaJIT) language itself is not limited, only the available environment and the set of usable modules are restricted.

The limitations can be adjusted with the untrusted_lua=off|strict|lax|sandbox|on setting.

See the sandboxing reference for more information.