Terminology

  • plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
  • upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.

Configuration

Global plugins

All plugins can be configured using the http:/kong:8001/plugins/ endpoint. A plugin which is not associated to any API, Service, Route or Consumer is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

form parameterdefaultdescription
nameThe name of the plugin to use, in this case

Configuring Quotas

After adding the plugin, you can increment the configured limits by adding the following response header:

Header-Name: Limit=Value [,Limit=Value]

Since X-Kong-Limit is the default header name (you can optionally change it), it will look like:

X-Kong-Limit: limitname1=2, limitname2=4

That will increment the limit limitname1 by 2 units, and limitname2 by 4 units.

You can optionally increment more than one limit by comma separating the entries. The header will be removed before returning the response to the original client.


Headers sent to the client

When this plugin is enabled, Kong will send some additional headers back to the client telling how many units are available and how many are allowed. For example if you created a limit/quota called "Videos" with a per-minute limit:

X-RateLimit-Limit-Videos-Minute: 10
X-RateLimit-Remaining-Videos-Minute: 9

or it will return a combination of more time limits, if more than one is being set:

X-RateLimit-Limit-Videos-Second: 5
X-RateLimit-Remaining-Videos-Second: 5
X-RateLimit-Limit-Videos-Minute: 10
X-RateLimit-Remaining-Videos-Minute: 10

If any of the limits configured is being reached, the plugin will return a HTTP/1.1 429 status code and an empty body.

Upstream Headers

The plugin will append the usage headers for each limit before proxying it to the upstream service, so that you can properly refuse to process the request if there are no more limits remaining. The headers are in the form of X-RateLimit-Remaining-{limit_name}, like:

X-RateLimit-Remaining-Videos: 3
X-RateLimit-Remaining-Images: 0

Keep up with the latest features