To manage API traffic for various user tiers (such as free, basic, and premium subscribers), you can create Consumer Groups for each tier and assign individual Consumers to these groups. Then, configure the Rate Limiting Advanced plugin to apply specific rate limits based on these groups. This setup allows you to enforce customized request limits for each tier, ensuring fair usage and optimizing performance for high-value users.
This is a Konnect tutorial. If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
The following Konnect items are required to complete this tutorial:
http://localhost:8000. You can set up Data Plane nodes for your Control Plane from the Gateway Manager in Konnect.Set the personal access token, the Control Plane name, the Control Plane URL, and the Konnect proxy URL as environment variables:
export DECK_KONNECT_TOKEN='YOUR KONNECT TOKEN'
export DECK_KONNECT_CONTROL_PLANE_NAME='YOUR CONTROL PLANE NAME'
export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
export KONNECT_PROXY_URL='KONNECT PROXY URL'
This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.
Export your license to an environment variable:
export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'
Run the quickstart script:
curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA
Once Kong Gateway is ready, you will see the following message:
Kong Gateway Ready
decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial you will first need to install decK.
For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:
Run the following command:
echo '
_format_version: "3.0"
services:
- name: example-service
url: http://httpbin.konghq.com/anything
routes:
- name: example-route
paths:
- "/anything"
service:
name: example-service
' | deck gateway apply -
To learn more about entities, you can read our entities documentation.
We need to set up authentication to identify the Consumer and apply rate limiting. In this guide, we’ll be using the Key Auth plugin, but you can use any authentication plugin.
Run the following command to configure the Key Auth plugin:
echo '
_format_version: "3.0"
plugins:
- name: key-auth
config:
key_names:
- apikey
' | deck gateway apply -
Before you can enable rate limiting for tiers of users, we first have to create Consumer Groups for each tier and then add Consumers to those groups. Consumer Groups are solely a way to organize Consumers of your APIs. In this guide, we’ll create three tiers (Free, Basic, and Premium), so we need to create a unique Consumer Group for each tier:
echo '
_format_version: "3.0"
consumer_groups:
- name: Free
- name: Basic
- name: Premium
' | deck gateway apply -
Now that you’ve added Consumer Groups for each tier, you can create three Consumers, one for each tier. Here, we’re manually adding Consumers for the sake of ease, but in a production environment, you could use a script that would automatically add Consumers to the correct groups as they sign up for a tier of service.
We’re also adding key auth credentials (key) to each Consumer so they can authenticate and we can test later that rate limiting was correctly configured for the different tiers:
echo '
_format_version: "3.0"
consumers:
- username: Amal
groups:
- name: Free
keyauth_credentials:
- key: amal
- username: Dana
groups:
- name: Basic
keyauth_credentials:
- key: dana
- username: Mahan
groups:
- name: Premium
keyauth_credentials:
- key: mahan
' | deck gateway apply -
Enable the Rate Limiting Advanced plugin for each tier:
echo '
_format_version: "3.0"
plugins:
- name: rate-limiting-advanced
consumer_group: Free
config:
limit:
- 3
window_size:
- 30
window_type: fixed
retry_after_jitter_max: 0
namespace: free
- name: rate-limiting-advanced
consumer_group: Basic
config:
limit:
- 5
window_size:
- 30
window_type: sliding
retry_after_jitter_max: 0
namespace: basic
- name: rate-limiting-advanced
consumer_group: Premium
config:
limit:
- 10
window_size:
- 30
window_type: sliding
retry_after_jitter_max: 0
namespace: premium
' | deck gateway apply -
This configures the different tiers like the following:
Now we can test that each rate limiting tier is working as expected by sending a series of HTTP requests (for example, six for Free Tier and seven for Basic Tier) to the endpoint with the appropriate API key with the goal of exceeding the configured rate limit for that tier. The tests wait for one second between requests to avoid overwhelming the server and test rate limits more clearly.
Test the rate limiting of the Free tier:
for _ in {1..4}; do
curl -i $KONNECT_PROXY_URL/anything \
-H "apikey:amal"
echo
done
for _ in {1..4}; do
curl -i http://localhost:8000/anything \
-H "apikey:amal"
echo
done
On the last request, you should get a 429 response with the message API rate limit exceeded.
Test the rate limiting of the Basic tier:
for _ in {1..6}; do
curl -i $KONNECT_PROXY_URL/anything \
-H "apikey:dana"
echo
done
for _ in {1..6}; do
curl -i http://localhost:8000/anything \
-H "apikey:dana"
echo
done
On the last request, you should get a 429 response with the message API rate limit exceeded.
Test the rate limiting of the Premium tier:
for _ in {1..11}; do
curl -i $KONNECT_PROXY_URL/anything \
-H "apikey:mahan"
echo
done
for _ in {1..11}; do
curl -i http://localhost:8000/anything \
-H "apikey:mahan"
echo
done
On the last request, you should get a 429 response with the message API rate limit exceeded.
If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.
curl -Ls https://get.konghq.com/quickstart | bash -s -- -d
Why can’t I use the regular Rate Limiting plugin to rate limit tiers of Consumers?
We use the Rate Limiting Advanced plugin because it supports sliding windows, which we use to apply the rate limiting logic while taking into account previous hit rates (from the window that immediately precedes the current) using a dynamic weight.