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:
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:
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.
The following functions are used to implement plugin logic at various entry-points of Kong Gateway’s execution life-cycle:
The HTTP module is used for plugins written for HTTP/HTTPS requests. It uses the following functions:
|
Function name |
Kong Gateway phase |
Nginx directives |
Request protocols |
Description |
|---|---|---|---|---|
init_worker
|
init_worker
|
init_worker_by_*
|
All protocols | Executed upon every Nginx worker process’s startup. |
configure
|
|
init_worker_by_*
|
All protocols | v3.4+ Executed every time the Kong Gateway plugin iterator is rebuilt (after changes to configure plugins). |
certificate
|
certificate
|
ssl_certificate_by_*
|
|
Executed during the SSL certificate serving phase of the SSL handshake. |
rewrite
|
rewrite
|
rewrite_by_*
|
All protocols |
Executed for every request upon its reception from a client as a rewrite phase handler.
In this phase, neither the Service nor the Consumer have been identified, hence this handler will only be executed if the plugin was configured as a global plugin. |
access
|
access
|
access_by_*
|
|
Executed for every request from a client and before it is being proxied to the upstream service. |
response
|
response
|
|
Replaces both header_filter() and body_filter(). Executed after the whole response has been received from the upstream service, but before sending any part of it to the client.
|
|
header_filter
|
header_filter
|
header_filter_by_*
|
|
Executed when all response headers bytes have been received from the upstream service. |
body_filter
|
body_filter
|
body_filter_by_*
|
|
Executed for each chunk of the response body received from the upstream service. Since the response is streamed back to the client, it can exceed the buffer size and be streamed chunk by chunk. This function can be called multiple times if the response is large. See the lua-nginx-module documentation for more details.
|
ws_handshake
|
ws_handshake
|
access_by_*
|
ws(s)
|
Executed for every request to a WebSocket service just before completing the WebSocket handshake. |
ws_client_frame
|
ws_client_frame
|
content_by_*
|
ws(s)
|
Executed for each WebSocket message received from the client. |
ws_upstream_frame
|
ws_upstream_frame
|
content_by_*
|
ws(s)
|
Executed for each WebSocket message received from the upstream service. |
log
|
log
|
log_by_*
|
|
Executed when the last response byte has been sent to the client. |
ws_close
|
ws_close
|
log_by_*
|
ws(s)
|
Executed after the WebSocket connection has been terminated. |
Note: If a module implements the
responsefunction, Kong Gateway will automatically activate the “buffered proxy” mode, as if thekong.service.request.enable_buffering()function had been called. Because of a current Nginx limitation, this doesn’t work for HTTP/2 or gRPC upstreams.
To reduce unexpected behavior changes, Kong Gateway does not start if a plugin implements both response and either header_filter or body_filter.
The Stream module is used for Plugins written for TCP and UDP stream connections. It uses the following functions:
|
Function name |
Kong Gateway phase |
Nginx directives |
Description |
|---|---|---|---|
init_worker
|
init_worker
|
init_worker_by_*
|
Executed upon every Nginx worker process’s startup. |
configure
|
|
init_worker_by_*
|
v3.4+ Executed every time the Kong Gateway plugin iterator is rebuilt (after changes to configure plugins). |
preread
|
preread
|
preread_by_*
|
Executed once for every connection. |
log
|
log
|
log_by_*
|
Executed once for each connection after it has been closed. |
certificate
|
certificate
|
ssl_certificate_by_*
|
Executed during the SSL certificate serving phase of the SSL handshake. |
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:
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.
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.
Every plugin supports a subset of these scopes.
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 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:
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.
See the following table for plugins and their compatible scopes:
All of the plugins bundled with Kong Gateway have a static priority.
This can be adjusted dynamically using the plugin’s ordering configuration parameter.
You can override the priority for any Kong Gateway plugin using each plugin’s ordering configuration parameter.
This determines plugin ordering during the access phase, and lets you create dynamic dependencies between plugins.
You can choose to run a particular plugin before or after a specified plugin or list of plugins.
The configuration looks like this:
pluginA:
ordering:
before|after:
access:
- pluginB
- pluginC
For example, let’s say you want to limit the amount of requests against your Gateway Service and Route before Kong requests authentication. The following example uses the Rate Limiting Advanced plugin with the Key Auth plugin as the authentication method:
Add this section to your declarative configuration file:
_format_version: "3.0"
plugins:
- name: rate-limiting
config:
minute: 5
policy: local
limit_by: ip
ordering:
before:
access:
- key-auth
Make the following request:
curl -i -X POST http://localhost:8001/plugins/ \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
"name": "rate-limiting",
"config": {
"minute": 5,
"policy": "local",
"limit_by": "ip"
},
"ordering": {
"before": {
"access": [
"key-auth"
]
}
}
}
'
Make the following request:
curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $KONNECT_TOKEN" \
--data '
{
"name": "rate-limiting",
"config": {
"minute": 5,
"policy": "local",
"limit_by": "ip"
},
"ordering": {
"before": {
"access": [
"key-auth"
]
}
}
}
'
Make sure to replace the following placeholders with your own values:
region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
See the Konnect API reference to learn about region-specific URLs and personal access tokens.
echo "
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: rate-limiting
namespace: kong
annotations:
kubernetes.io/ingress.class: kong
labels:
global: 'true'
config:
minute: 5
policy: local
limit_by: ip
ordering:
before:
access:
- key-auth
plugin: rate-limiting
" | kubectl apply -f -
terraform {
required_providers {
konnect = {
source = "kong/konnect"
}
}
}
provider "konnect" {
personal_access_token = "$KONNECT_TOKEN"
server_url = "https://us.api.konghq.com/"
}
Add the following to your Terraform configuration to create a Konnect Gateway Plugin:
resource "konnect_gateway_plugin_rate_limiting" "my_rate_limiting" {
enabled = true
config = {
minute = 5
policy = "local"
limit_by = "ip"
}
ordering = {
before = {
access = ["key-auth"]
}
}
control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}
For example, you may want to first transform a request with the Request Transformer plugin, then request authentication. You can change the order of the authentication plugin (Basic Auth, in this example) so that it always runs after transformation:
Add this section to your declarative configuration file:
_format_version: "3.0"
plugins:
- name: basic-auth
ordering:
after:
access:
- request-transformer
Make the following request:
curl -i -X POST http://localhost:8001/plugins/ \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
"name": "basic-auth",
"ordering": {
"after": {
"access": [
"request-transformer"
]
}
}
}
'
Make the following request:
curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $KONNECT_TOKEN" \
--data '
{
"name": "basic-auth",
"ordering": {
"after": {
"access": [
"request-transformer"
]
}
}
}
'
Make sure to replace the following placeholders with your own values:
region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
See the Konnect API reference to learn about region-specific URLs and personal access tokens.
echo "
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: basic-auth
namespace: kong
annotations:
kubernetes.io/ingress.class: kong
labels:
global: 'true'
ordering:
after:
access:
- request-transformer
plugin: basic-auth
" | kubectl apply -f -
terraform {
required_providers {
konnect = {
source = "kong/konnect"
}
}
}
provider "konnect" {
personal_access_token = "$KONNECT_TOKEN"
server_url = "https://us.api.konghq.com/"
}
Add the following to your Terraform configuration to create a Konnect Gateway Plugin:
resource "konnect_gateway_plugin_basic_auth" "my_basic_auth" {
enabled = true
ordering = {
after = {
access = ["request-transformer"]
}
}
control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}
If using dynamic ordering, manually test all configurations, and handle this feature with care. There are a number of considerations that can affect your environment:
Consumer scoping: If you have Consumer-scoped plugins anywhere in your Workspace or Control Plane, you can’t use dynamic plugin ordering.
Consumer mapping and dynamic plugin ordering both run in the access phase, but the order of the plugins must be determined after Consumer mapping has happened.
Kong Gateway can’t reliably change the order of the plugins in relation to mapped Consumers.
Cascading deletes: Detecting if a plugin has a dependency to a deleted plugin isn’t supported, so handle your configuration with care.
Performance: Dynamic plugin ordering requires sorting plugins during a request, which adds latency to the request. In some cases, this might be compensated for when you run rate limiting before an expensive authentication plugin.
Re-ordering any plugin in a Workspace or Control Plane has performance implications to all other plugins within the same environment. If possible, consider offloading plugin ordering to a separate environment.
Validation: Validating dynamic plugin ordering is a non-trivial task and would require insight into the user’s business logic. Kong Gateway tries to catch basic mistakes, but it can’t detect all potentially dangerous configurations.
Plugins support different protocols.
See the following table for plugins and their compatible protocols:
Kong has many bundled plugins available, all of which have their own specific configurations and examples. See all Kong plugins for their individual configurations.
Here’s an example of configuration for the ACL plugin:
Add this section to your declarative configuration file:
_format_version: "3.0"
plugins:
- name: acl
config:
allow:
- dev
- admin
hide_groups_header: false
Make the following request:
curl -i -X POST http://localhost:8001/plugins/ \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
"name": "acl",
"config": {
"allow": [
"dev",
"admin"
],
"hide_groups_header": false
}
}
'
Make the following request:
curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $KONNECT_TOKEN" \
--data '
{
"name": "acl",
"config": {
"allow": [
"dev",
"admin"
],
"hide_groups_header": false
}
}
'
Make sure to replace the following placeholders with your own values:
region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
See the Konnect API reference to learn about region-specific URLs and personal access tokens.
echo "
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: acl
namespace: kong
annotations:
kubernetes.io/ingress.class: kong
labels:
global: 'true'
config:
allow:
- dev
- admin
hide_groups_header: false
plugin: acl
" | kubectl apply -f -
terraform {
required_providers {
konnect = {
source = "kong/konnect"
}
}
}
provider "konnect" {
personal_access_token = "$KONNECT_TOKEN"
server_url = "https://us.api.konghq.com/"
}
Add the following to your Terraform configuration to create a Konnect Gateway Plugin:
resource "konnect_gateway_plugin_acl" "my_acl" {
enabled = true
config = {
allow = ["dev", "admin"]
hide_groups_header = false
}
control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}