Secure your API proxy's target backend against severe traffic spikes and denial of service attacks.

The Flood Control Plugin is a custom Kong plugin designed to control sudden bursts of traffic, similar to the Spike Arrest policy in Apigee or Spike Control policy in Mulesoft. It limits the rate of incoming requests based on either the client IP address or the authenticated consumer, helping to smooth out traffic spikes and protect backend services from overload.

Unlike traditional rate limiting, which counts requests over a fixed time window, Flood Control focuses on smoothing the rate of traffic flow in real-time.

By using this plugin, you can:

• Protect APIs from DDoS attacks and malicious traffic bursts.
• Prevent backend system overload due to sudden spikes in traffic.
• Reduce the risk of system downtime by smoothing out request rates.
• Improve overall API reliability and performance under load.

You can deploy the Flood Control plugin using one of the following methods:

1. Copy your plugin code (schema.lua and handler.lua) to the Kong node under:

   /usr/local/share/lua/5.1/kong/plugins/flood-control
   

   Make sure to give appropriate file permissions to the plugin directory and all files in it.

   e.g. In Unix, chmod 777 *.lua

2. Update the KONG_PLUGINS environment variable or kong.conf file: This enables use of flood-control plugin

   export KONG_PLUGINS=bundled,flood-control

3. Allocate shared memory: This enables to store Identifier and the time when last API call was made by this identifier

   vi /usr/local/share/lua/5.1/kong/templates/nginx_kong.lua
   ## add below line near similar lines
   lua_shared_dict flood_control 10m;

4. Restart Kong.

   kong restart -c /etc/kong/kong.conf

Follow the official Kong guide to build a Docker image with your plugin: 👉 Deploy Plugins - Kong Docs

Package and install your plugin using LuaRocks: 👉 Installation and Distribution - Kong Docs

To use the plugin in sevice, route or global:

1. Enable the plugin on a Service, Route or Global.
2. Select the Identifier Type: ip or consumer.
3. Enter the Rate: The number of API requests that can be made per time unit (second/minute).
4. Select the Unit: second or minute.

Example configuration:

curl -i -X POST http://localhost:8001/services/my-service/plugins \
  --data "name=flood-control" \
  --data "config.identifier_type=ip" \
  --data "config.rate=5" \
  --data "config.interval=minute"

Here are some test scenarios:

To ensure simplicity in understanding the plugin behaviour, I added below simple test cases.

Use tools like curl, insomnia or postman to simulate the traffic and observe plugin behavior.

Use Flood Control when you want to protect your backend from sudden traffic spikes or denial-of-service attacks.

Avoid using Flood Control when you need to count and limit total number of requests over a time window. For that, use the Rate Limiting or Rate Limiting Advanced plugin.

• Database Storage: ❌ No
• Shared Memory Storage: ✅ Yes

The plugin uses shared memory for fast, in-memory request tracking, ensuring low latency and high performance.