You are browsing unreleased documentation. See the latest documentation here.

Rate Limiting

Rate limiting is used to control the rate of requests sent to an upstream service. It can be used to prevent DoS attacks, limit web scraping, and other forms of overuse. Without rate limiting, clients have unlimited access to your upstream services, which may negatively impact availability.

The Rate Limiting plugin

Kong Gateway imposes rate limits on clients through the use of the Rate Limiting plugin. When rate limiting is enabled, clients are restricted in the number of requests that can be made in a configurable period of time. The plugin supports identifying clients as consumers or by the client IP address of the requests.

This tutorial uses the Rate Limiting plugin. Also available is the Rate Limiting Advanced plugin. The advanced version provides additional features like support for the sliding window algorithm and advanced Redis support for greater performance.

Managing rate limiting

The following tutorial walks through managing rate limiting across various aspects in Kong Gateway.

Prerequisites

This chapter is part of the Get Started with Kong series. For the best experience, it is recommended that you follow the series from the beginning.

Start with the introduction Get Kong, which includes tool prerequisites and instructions for running a local Kong Gateway.

Step two of the guide, Services and Routes, includes instructions for installing a mock service used throughout this series.

If you haven’t completed these steps already, complete them before proceeding.

Global rate limiting

Installing the plugin globally means every proxy request to Kong Gateway will be subject to rate limit enforcement.

Enable rate limiting

The rate limiting plugin is installed by default on Kong Gateway, and can be enabled by sending a POST request to the plugins object on the Admin API:
```
curl -i -X POST http://localhost:8001/plugins \
  --data name=rate-limiting \
  --data config.minute=5 \
  --data config.policy=local
```
This command has instructed Kong Gateway to impose a maximum of 5 requests per minute per client IP address for all routes and services.

The policy configuration determines where Kong Gateway retrieves and increments limits. See the full plugin configuration reference for details.

You will see a response that contains the new plugin configuration, including identification information similar to:
```
...
"id": "fc559a2d-ac80-4be8-8e43-cb705524be7f",
"name": "rate-limiting",
"enabled": true
...
```
Validate

After configuring rate limiting, you can verify that it was configured correctly and is working, by sending more requests than allowed in the configured time limit.
Command Line

Web browser
Run the following command to quickly send 6 mock requests:
for _ in {1..6}; do curl -s -i localhost:8000/mock/anything; echo; sleep 1; done
Open http://localhost:8000/mock/anything in your browser and refresh the page 6 times within 1 minute.
After the 6th request, you should receive a 429 “API rate limit exceeded” error:
```
{
   "message": "API rate limit exceeded"
}
```

Service level rate limiting

The Rate Limiting plugin can be enabled for specific services. The request is the same as above, but posted to the service URL:

curl -X POST http://localhost:8001/services/example_service/plugins \
   --data "name=rate-limiting" \
   --data config.minute=5 \
   --data config.policy=local

Route level rate limiting

The Rate Limiting plugin can be enabled for specific routes. The request is the same as above, but posted to the route URL:

curl -X POST http://localhost:8001/routes/example_route/plugins \
   --data "name=rate-limiting" \
   --data config.minute=5 \
   --data config.policy=local

Consumer level rate limiting

In Kong Gateway, consumers are an abstraction that defines a user of a service. Consumer-level rate limiting can be used to limit request rates per consumer.

Create a consumer

Consumers are created using the consumer object in the Admin API.

curl -X POST http://localhost:8001/consumers/ \
  --data username=jsmith

Enable rate limiting for the consumer

Using the consumer id, enable rate limiting for all routes and services for the jsmith consumer.

curl -X POST http://localhost:8001/plugins \
   --data "name=rate-limiting" \
   --data "consumer.username=jsmith" \
   --data "config.second=5"

Advanced rate limiting

In high scale production scenarios, effective rate limiting may require advanced techniques. The basic Rate Limiting plugin described above only allows you to define limits over fixed-time windows. Fixed-time windows are sufficient for many cases, however, there are disadvantages:

Bursts of requests around the boundary time of the fixed window, may result in strained resources as the window counter is reset in the middle of the traffic burst.
Multiple client applications may be waiting for the fixed-time window to reset so they can resume making requests. When the fixed-window resets, multiple clients may flood the system with requests, causing a stampeding effect on your upstream services.

The Rate Limiting Advanced plugin is an enhanced version of the Rate Limiting plugin. The advanced plugin provides additional limiting algorithm capabilities and superior performance compared to the basic plugin. For more information on advanced rate limiting algorithms, see How to Design a Scalable Rate Limiting Algorithm with Kong API.

Previous Services and Routes

Next Proxy Caching