Kong Rate Limiting Plugin — Configuring API Gateway Throttling

In this tutorial, you will learn about Kong Rate Limiting Plugin. We cover key concepts, practical examples, and best practices to help you master this topic.

Kong API Gateway provides a rate limiting plugin that supports multiple strategies (local, cluster, Redis) and can be applied globally, per-route, per-service, or per-consumer for flexible API traffic control.

What You'll Learn

• How to install and configure the Kong rate limiting plugin
• How to apply rate limits globally, per-route, and per-consumer
• How to choose between local, cluster, and Redis strategies

Why It Matters

Kong's rate limiting plugin provides a declarative, no-code approach to rate limiting at the gateway level. You can add and change rate limits without modifying application code, making it ideal for API teams that want centralized traffic policy management.

Real-World Use

DodaTech's API runs behind Kong Gateway. The rate limiting plugin is configured with Redis backend for cluster-wide consistency: 10 req/min for free consumers, 100 req/min for Pro consumers, and custom limits for enterprise partners. All configured through Kong's Admin API without touching application code.

flowchart LR
    A["Client"] --> B["Kong Gateway"]
    B --> C["Rate Limiting\nPlugin"]
    C --> D{"Strategy:\nRedis"}
    D --> E["Redis\nCluster"]
    C --> F{"Within\nlimit?"}
    F -->|"Yes"| G["Upstream\nService"]
    F -->|"No"| H["429 Rate\nLimited"]
    style B fill:#dbeafe,stroke:#2563eb
    style E fill:#fef3c7,stroke:#d97706
    style H fill:#fecaca,stroke:#dc2626

Enabling the Rate Limiting Plugin

# Enable rate limiting plugin globally
curl -i -X POST http://localhost:8001/plugins \
  --data "name=rate-limiting" \
  --data "config.second=5" \
  --data "config.minute=100" \
  --data "config.hour=1000" \
  --data "config.policy=redis" \
  --data "config.redis_host=redis-service" \
  --data "config.redis_port=6379"

Per-Consumer Rate Limits

import requests

KONG_ADMIN = "http://localhost:8001"

# Create a consumer
consumer = requests.post(f"{KONG_ADMIN}/consumers", json={
    "username": "partner-pro",
    "custom_id": "pro-123"
})

# Apply rate limiting plugin to specific consumer
plugin = requests.post(
    f"{KONG_ADMIN}/consumers/partner-pro/plugins",
    json={
        "name": "rate-limiting",
        "config": {
            "minute": 500,
            "hour": 10000,
            "policy": "redis",
            "redis_host": "redis-service",
            "fault_tolerant": True,
            "hide_client_headers": False
        }
    }
)
print(f"Rate limit plugin created for partner-pro: {plugin.status_code}")

Per-Route Configuration

# Apply rate limiting to specific routes
routes = {
    "auth": {"path": "/api/auth", "limit": "5 per minute"},
    "search": {"path": "/api/search", "limit": "30 per minute"},
    "public": {"path": "/api/public", "limit": "100 per minute"}
}

for name, config in routes.items():
    # Create route-specific rate limit
    response = requests.post(
        f"{KONG_ADMIN}/plugins",
        json={
            "name": "rate-limiting",
            "route": {"name": name},
            "config": {
                "minute": int(config["limit"].split()[0]),
                "policy": "redis",
                "redis_host": "redis-service"
            }
        }
    )
    print(f"{name}: {response.status_code}")

Custom Response Headers

# Configure rate limit response headers
plugin_config = {
    "name": "rate-limiting",
    "config": {
        "minute": 100,
        "policy": "redis",
        "redis_host": "redis-service",
        "limit_by": "consumer",
        "header_name": "X-Kong-RateLimit",
        "response_headers": {
            "X-RateLimit-Limit": "minute",
            "X-RateLimit-Remaining": "remaining",
            "X-RateLimit-Reset": "time_to_reset"
        }
    }
}

response = requests.post(
    f"{KONG_ADMIN}/plugins",
    json=plugin_config
)

Common Mistakes

1. Using Local Policy in Multi-Node Deployments

Multiple Kong nodes with local policy have independent counters, allowing bypass. Always use Redis or cluster policy in production.

2. Not Setting fault_tolerant=True

When Redis is down, Kong can still allow requests (fault-tolerant) or reject them. In production, set fault_tolerant=True to avoid downtime if Redis fails.

3. Confusing limit_by Options

limit_by=consumer limits per authenticated consumer; limit_by=ip limits per client IP; limit_by=credential limits per API key. Choose the right one for your use case.

4. Not Testing Rate Limits in Dev Mode

Rate limits apply immediately. In dev mode, set high limits to avoid blocking yourself while testing.

5. Forgetting to Clear Redis on Plugin Changes

Rate limit counters persist in Redis. When you change plugin config, flush relevant Redis keys to reset counters.

Practice Questions

1. What rate limiting policies does Kong support?
2. Why should you use Redis policy in production?
3. How do you apply rate limits to a specific consumer?
4. What happens if Redis is unavailable with fault_tolerant=False?
5. How do you configure custom response headers?

Answers

1. Local (in-memory), Cluster (cluster sync), Redis. 2. For consistent limits across multiple Kong nodes. 3. Create a consumer and apply the plugin to that consumer. 4. Kong rejects all requests with a 500 error. 5. Configure the config.response_headers field.

Challenge

Build a Kong rate limiting configuration script that: creates three consumers (free, pro, enterprise), applies per-consumer rate limits with Redis backend, configures per-route limits for auth and search endpoints, sets up custom response headers, and tests each limit with sample requests.

FAQ

Mini Project

Create a docker-compose setup with Kong Gateway and Redis, configure rate limiting plugins for multiple consumers and routes, create a test client script that demonstrates each rate limit being enforced, and set up Kong's Prometheus plugin to export rate limit metrics.

What's Next

• Learn about Express rate-limit middleware for Node.js applications
• Explore Django ratelimit for Python web apps
• Continue to distributed rate limiting with Redis cluster