Streaming custom plugins

You can define a custom plugin directly in Kong entity configuration.

Kong Gateway can stream custom plugins from the control plane to the data plane. The control plane becomes the single source of truth for plugin versions. You only need to define the plugin once, and Kong Gateway handles distribution to all data planes in the same control plane.

A streamed custom plugin must meet the following requirements:

• Unique name per plugin
• One plugin handler and one schema
• Cannot run in the init_worker phase or create timers
• Must be written in Lua

You can also define streaming plugins in traditional or DB-less mode. In these modes, the plugin is defined in the entity configuration directly, and no separate files are needed.

Keep the following custom plugin limitations in mind for streaming plugins:

• Only schema.lua and handler.lua are supported. Plugin logic must be self-contained in these two modules. You can’t use DAOs, custom APIs, migrations, or multiple Lua modules.
• Custom modules cannot be required when plugin sandboxing is enabled. External Lua files or shared libraries can’t be loaded.
• Custom validation must be implemented in handler.lua, not schema.lua. In handler.lua, it can be logged and handled as part of plugin business logic.
• Plugins can’t read/write to the Kong Gateway filesystem.

To create streaming plugins, you must have the following permissions:

• Konnect: One of the following control plane roles: ServiceAdmin, RouteAdmin, PluginAdmin, CPAdmin, or Deployer.
• Self-managed Kong Gateway: super-admin or admin role.

curl -X POST http://localhost:8001/custom-plugins \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
      --arg name "my-example-plugin" \
      --arg handler "$(cat handler.lua)" \
      --arg schema "$(cat schema.lua)" \
      '{"name":$name,"handler":$handler,"schema":$schema}')"

curl -X POST http://localhost:8001/custom-plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-example-plugin",
    "schema": "SCHEMA_LUA",
    "handler": "HANDLER_LUA"
  }'

curl -X POST $KONNECT_CONTROL_PLANE_URL/v2/control-planes/$CONTROL_PLANE_ID/core-entities/custom-plugins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KONNECT_TOKEN" \
  -d "$(jq -n \
      --arg name "my-example-plugin" \
      --arg handler "$(cat handler.lua)" \
      --arg schema "$(cat schema.lua)" \
      '{"name":$name,"handler":$handler,"schema":$schema}')" \
    | jq

_format_version: "3.0"
custom_plugins:
 - name: my-example-plugin
   schema: |
    return {
      name = "my-example-plugin",
      fields = {
        {
          config = {
            type = "record",
            fields = {
              { example_field = { type = "string", required = true } },
              { another_example_field = { type = "string", required = true } },
            },
          },
        },
      },
    }
   handler: |
    local MyPluginHandler = {
      PRIORITY = 1000,
      VERSION = "0.0.1",
    }

    return MyPluginHandler

Once added to configuration, you can manage custom plugins using any of the following methods:

• decK
• Control Plane Config API
• Konnect UI

For example:

plugins:
  - name: my-example-plugin
    condition: '!http.path.contains("something")'
    config:
      example_field: foo
      another_example_field: bar

For a complete end-to-end example, see Stream Kong Gateway plugins.

If you need to make any changes to the handler or schema of the streaming plugin, we recommend the following approach for safe migration:

1. Start a migration/maintenance window.
2. Create a new version of the custom plugin.
3. Update all the instances of the custom plugin to comply with the new version’s schema.
4. Remove the old version of the custom plugin.
5. Stop the migration/maintenance window.