You are browsing documentation for an older version. See the latest documentation here.
About Kong Plugins
What are plugins?
Kong Gateway is a Lua application designed to load and execute Lua or Go modules, which we commonly refer to as plugins. Kong provides a set of standard Lua plugins that get bundled with Kong Gateway and Konnect. The set of plugins you have access to depends on your license tier.
Custom plugins can also be developed by the Kong Community and are supported and maintained by the plugin creators. If they are published on the Kong Plugin Hub, they are called Community or Third-Party plugins.
Why use plugins?
Plugins provide advanced functionality and extend the use of the Kong Gateway, which allows you to add new features to your implementation. Plugins can be configured to run in a variety of contexts, ranging from a specific route to all upstreams, and can execute actions inside Kong before or after a request has been proxied to the upstream API, as well as on any incoming responses.
Plugin compatibility with deployment types
Kong Gateway can be deployed in a variety of ways, and not all plugins are fully compatible with each mode. See Plugin Compatibility for a comparison.
Precedence
A single plugin instance always runs once per request. The configuration with which it runs depends on the entities it has been configured for. Plugins can be configured for various entities, combinations of entities, or even globally. 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 amount of entities configured to a specific plugin directly correlate to its priority. The more entities configured to a plugin the higher its order of precedence is. The complete order of precedence for plugins configured to multiple entities is:
- Plugins configured on a combination of a consumer, a route, and a service. (Consumer means the request must be authenticated).
- Plugins configured on a combination of a consumer group, service, and a route. (Consumer group means the request must be authenticated).
- Plugins configured on a combination of a consumer and a route. (Consumer means the request must be authenticated).
- Plugins configured on a combination of a consumer and a service.
- Plugins configured on a consumer group and route.
- Plugins configured on a consumer group and service.
- Plugins configured on a route and service.
- Plugins configured on a consumer.
- Plugins configured on a consumer group.
- Plugins configured on a route.
- Plugins configured on a service.
- Plugins configured globally.
Precedence for consumer groups
When a consumer is a member of two consumer groups, each with a scoped plugin, Kong Gateway ensures deterministic behavior by executing only one of these plugins. However, the specific rules that govern this behavior are not defined and are subject to change in future releases.
Terminology
- Plugin
- An extension to the Kong Gateway.
-
For plugins developed and maintained by Kong, plugin versioning generally has no impact on your implementation, other than to find out which versions of Kong contain which plugin features. Kong plugins are bundled with the Kong Gateway, so compatible plugin versions are already associated with the correct version of Kong.
- Kong plugin or Kong bundled plugin
- A plugin developed, maintained, and supported by Kong.
-
Because third-party plugins are not maintained by Kong and are not bundled with the Kong Gateway, version compatibility is a bigger concern. See each individual plugin’s page for its tested compatibility.
-
If the versions on the plugin page are outdated, contact the maintainer directly.
- Plugin supported by 3rd party
- A plugin in the category “Contact 3rd party for support”. This is a custom plugin developed, tested, and maintained by an external developer, not by Kong. Unless the plugin is explicitly labelled as a technical partner, Kong does not test these plugins, or update their version compatibility.
- Technical partner plugin
- A 3rd party custom plugin that has been carefully validated by Kong and has met certain standards. These plugins are still developed, tested, and maintained by an external developer, not by Kong. The plugin owner also maintains the plugin’s version compatibility with Kong Gateway.
Developing custom plugins
Kong provides an entire development environment for developing plugins, including Lua and Go SDKs, database abstractions, migrations, and more.
Plugins consist of modules interacting with the request/response objects or streams via a Plugin Development Kit (or PDK) to implement arbitrary logic. Kong provides PDKs for two languages: Lua and Go. Both of 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, check out the PDK documentation:
Contributing custom plugins
If you are interested in sharing your custom plugin with other Kong users, you must also submit plugin reference documentation to the Kong Plugin Hub. See the contribution guidelines for adding documentation.
Other key concepts
- For more information about available plugins, see the Plugin Hub.
- Stages of software availability