Plugins

Kong Gateway is a Lua application designed to load and execute modules. These modules, called plugins, allow you to add more features to your implementation.

Kong provides a set of standard Lua plugins that get bundled with Kong Gateway and Konnect.

You can also develop custom plugins, adding your own custom functionality to Kong Gateway.

Kong provides an entire development environment for developing plugins, including Plugin Development Kits (or PDKs), database abstractions, migrations, and more.

Plugins consist of modules interacting with the request/response objects or streams via a PDK to implement arbitrary logic. Kong provides PDKs in the following languages:

• Lua
• Go
• Python
• JavaScript

These PDKs are sets of functions that a plugin can use to facilitate interactions between plugins and the core (or other components) of Kong.

To start creating your own plugins, review the Getting Started documentation, or see the following references:

• Plugin Development Kit reference
• Custom plugins reference

A Kong Gateway plugin allows you to inject custom logic at several entrypoints in the lifecycle of a request, response, or TCP stream connection as it is proxied by Kong Gateway.

Plugin contexts

The following functions are used to implement plugin logic at various entry-points of Kong Gateway’s execution life-cycle:

All of those functions, except init_worker and configure, take one parameter which is given by Kong Gateway upon its invocation: the configuration of your plugin. This parameter is a Lua table, and contains values defined by your users, according to your plugin’s schema (described in the schema.lua module). The configure is called with an array of all the enabled plugin configurations for the particular plugin (or in case there is no active configurations to plugin, a nil is passed). init_worker and configure happens outside requests or frames, while the rest of the phases are bound to incoming request/frame.

Note that UDP streams don’t have real connections. Kong Gateway will consider all packets with the same origin and destination host and port as a single connection. After a configurable time without any packet, the connection is considered closed and the log function is executed.

You can run plugins in various contexts, depending on your environment needs. Each plugin can run globally, or be scoped to some combination of the following:

• Gateway Services
• Routes
• Consumers
• Consumer Groups

Using scopes, you can customize how Kong Gateway handles functions in your environment, either before a request is sent to your upstream services or after it receives a response. For example, if you apply a plugin to a single Route, that plugin will only trigger when a request matches the Route’s specific path.

Global scope

A global plugin is not associated to any Service, Route, Consumer, or Consumer Group is considered global, and will be run on every request, regardless of any other configuration.

• In self-managed Kong Gateway Enterprise, the plugin applies to every entity in a given Workspace.
• In self-managed open-source Kong Gateway, the plugin applies to your entire environment.
• In Konnect, the plugin applies to every entity in a given Control Plane.

Every plugin supports a subset of these scopes.

Plugin precedence

A plugin can have multiple instances in the same configuration. Different instances can be used to apply the plugin to various entities, combinations of entities, or even globally. You can give each plugin instance a unique name to help identify it. The instance name itself doesn’t affect processing - it acts like an internal label instead.

A single plugin instance always runs once per request. The configuration with which it runs depends on the entities it has been configured for.

This is useful, for example, when you want to configure a plugin a certain way for most requests but make authenticated requests behave slightly differently.

Therefore, there is an order of precedence for running a plugin when it has been applied to different entities with different configurations. The number of entities configured to a specific plugin directly correlates to its priority. The more entities a plugin is configured for, the higher its order of precedence.

The complete order of precedence for plugins configured to multiple entities is:

1. Consumer + Route + Service: Highest precedence, affecting authenticated requests that match a specific Consumer on a particular Route and Service.
2. Consumer group + Service + Route: Affects groups of authenticated users across specific Services and Routes.
3. Consumer + Route: Targets authenticated requests from a specific Consumer on a particular Route.
4. Consumer + Service: Applies to authenticated requests from a specific Consumer accessing any Route within a given Service.
5. Consumer group + Route: Affects groups of authenticated users on specific Routes.
6. Consumer group + Service: Applies to all Routes within a specific Service for groups of authenticated users.
7. Route + Service: Targets all Consumers on a specific Route and Service.
8. Consumer: Applies to all requests from a specific, authenticated Consumer across all Routes and Services.
9. Consumer Group: Affects all Routes and Services for a designated group of authenticated users.
10. Route: Specific to given Route.
11. Service: Specific to given Service.
12. Globally configured plugins: Lowest precedence, applies to all requests across all Services and Routes regardless of Consumer status.

Note on precedence for Consumer Groups

When a Consumer is a member of two Consumer Groups, each with a scoped instance of the same plugin, Kong Gateway ensures deterministic behavior by executing only one of these plugin instances. Currently, this is determined by the Consumer Group name, in alphabetical order. For example, if you have two Consumer Groups, A and B, each with an instance of the Rate Limiting Advanced plugin, the plugin in Consumer Group A will be applied.

The specific rules that govern this behavior are not defined and are subject to change in future releases.

Supported scopes by plugin

See the following table for plugins and their compatible scopes: