You are browsing documentation for an outdated version. See the latest documentation here.

Using Redis for rate limiting

Kong can rate limit traffic without any external dependency. Kong stores the request counters in-memory and each Kong node applies the rate limiting policy independently without synchronization of information. However, if Redis is available in your cluster, Kong can take advantage of it and synchronize the rate limit information across multiple Kong nodes and enforce a slightly different rate limiting policy.

Learn to use Redis for rate limiting in a multi-node Kong deployment.

You can use the Kong Enterprise Secrets Management feature along with the example rate-limiting plugin. If you have an existing plugin that you wish to use Secrets Management with, you can skip directly to the Secrets Management section and use it for your plugin instead of the example rate-limiting plugin.

Deploy an upstream HTTP application

To proxy requests, you need an upstream application to send a request to. Deploying this echo server provides a simple application that returns information about the Pod it’s running in:

echo "
apiVersion: v1
kind: Service
metadata:
  labels:
    app: echo
  name: echo
spec:
  ports:
  - port: 1025
    name: tcp
    protocol: TCP
    targetPort: 1025
  - port: 1026
    name: udp
    protocol: TCP
    targetPort: 1026
  - port: 1027
    name: http
    protocol: TCP
    targetPort: 1027
  selector:
    app: echo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: echo
  name: echo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echo
  strategy: {}
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: echo
    spec:
      containers:
      - image: kong/go-echo:latest
        name: echo
        ports:
        - containerPort: 1027
        env:
          - name: NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
          - name: POD_NAME
            valueFrom:
              fieldRef:
                fieldPath: metadata.name
          - name: POD_NAMESPACE
            valueFrom:
              fieldRef:
                fieldPath: metadata.namespace
          - name: POD_IP
            valueFrom:
              fieldRef:
                fieldPath: status.podIP
        resources: {}
" | kubectl apply -f -

The results should look like this:

service/echo created
deployment.apps/echo created

Create a configuration group

Ingress and Gateway APIs controllers need a configuration that indicates which set of routing configuration they should recognize. This allows multiple controllers to coexist in the same cluster. Before creating individual routes, you need to create a class configuration to associate routes with:

echo "
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: kong
spec:
  controller: ingress-controllers.konghq.com/kong
" | kubectl apply -f -

ingressclass.networking.k8s.io/kong configured

echo "
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: kong
  annotations:
    konghq.com/gatewayclass-unmanaged: 'true'

spec:
  controllerName: konghq.com/kic-gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: kong
spec:
  gatewayClassName: kong
  listeners:
  - name: proxy
    port: 80
    protocol: HTTP
" | kubectl apply -f -

gatewayclass.gateway.networking.k8s.io/kong created
gateway.gateway.networking.k8s.io/kong created

kubectl get gateway kong

NAME   CLASS   ADDRESS        READY   AGE
kong   kong    203.0.113.42   True    4m46s

Kong Ingress Controller recognizes the kong IngressClass and konghq.com/kic-gateway-controller GatewayClass by default. Setting the CONTROLLER_INGRESS_CLASS or CONTROLLER_GATEWAY_API_CONTROLLER_NAME environment variable to another value overrides these defaults.

Add routing configuration

Create routing configuration to proxy /echo requests to the echo server:

echo "
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: echo
     annotations:
       konghq.com/strip-path: 'true'
   spec:
     ingressClassName: kong
     rules:
     - host: kong.example
       http:
         paths:
         - path: /echo
           pathType: ImplementationSpecific
           backend:
             service:
               name: echo
               port:
                 number: 1027
   " | kubectl apply -f -

echo "
   apiVersion: gateway.networking.k8s.io/v1beta1
   kind: HTTPRoute
   metadata:
     name: echo
     annotations:
       konghq.com/strip-path: 'true'
   spec:
     parentRefs:
     - name: kong
     hostnames:
     - 'kong.example'
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /echo
       backendRefs:
       - name: echo
         kind: Service
         port: 1027
   " | kubectl apply -f -

The results should look like this:

ingress.networking.k8s.io/proxy-from-k8s-to-httpbin created

httproute.gateway.networking.k8s.io/echo created

Test the routing rule:

curl -i -H 'Host:kong.example' $PROXY_IP/echo

The results should look like this:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 140
Connection: keep-alive
Date: Fri, 21 Apr 2023 12:24:55 GMT
X-Kong-Upstream-Latency: 0
X-Kong-Proxy-Latency: 1
Via: kong/3.2.2

Welcome, you are connected to node docker-desktop.
Running on Pod echo-7f87468b8c-tzzv6.
In namespace default.
With IP address 10.1.0.237.
...

If everything is deployed correctly, you should see the above response. This verifies that Kong Gateway can correctly route traffic to an application running inside Kubernetes.

Set up rate limiting

1. Create an instance of the rate-limiting plugin.

    echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: rate-limit
      annotations:
        kubernetes.io/ingress.class: kong
    config:
      minute: 5
      policy: local
    plugin: rate-limiting
    " | kubectl apply -f -
   

   The results should look like this:

    kongplugin.configuration.konghq.com/rate-limit created
   

2. Associate the plugin with the Service.

    kubectl annotate service echo konghq.com/plugins=rate-limit
   

   The results should look like this:

    service/echo annotated
   

3. Send requests through this Service to rate limiting response headers.

    curl -si -H 'Host:kong.example' $PROXY_IP/echo | grep RateLimit
   

   The results should look like this:

    RateLimit-Limit: 5
    X-RateLimit-Remaining-Minute: 4
    X-RateLimit-Limit-Minute: 5
    RateLimit-Reset: 60
    RateLimit-Remaining: 4
   

4. Send repeated requests to decrement the remaining limit headers, and block requests after the fifth request.

    for i in `seq 6`; do curl -sv -H 'Host:kong.example' $PROXY_IP/echo 2>&1 | grep "< HTTP"; done
   

   The results should look like this:

    < HTTP/1.1 200 OK
    < HTTP/1.1 200 OK
    < HTTP/1.1 200 OK
    < HTTP/1.1 200 OK
    < HTTP/1.1 200 OK
    < HTTP/1.1 429 Too Many Requests
   

Scale to multiple pods

1. Scale your Deployment to three replicas, to test with multiple proxy instances.

    kubectl scale --replicas 3 -n kong deployment kong-gateway
   

   The results should look like this:

    deployment.apps/kong-gateway scaled
   

2. Check if the status of all the Pods that are READY is Running using the command kubectl get pods -n kong.

3. Sending requests to this Service does not reliably decrement the remaining counter.

    for i in `seq 10`; do curl -sv -H 'Host:kong.example' $PROXY_IP/echo 2>&1 | grep "X-RateLimit-Remaining-Minute"; done
   

   The results should look like this:

    < X-RateLimit-Remaining-Minute: 4
    < X-RateLimit-Remaining-Minute: 4
    < X-RateLimit-Remaining-Minute: 3
    < X-RateLimit-Remaining-Minute: 4
    < X-RateLimit-Remaining-Minute: 3
    < X-RateLimit-Remaining-Minute: 2
    < X-RateLimit-Remaining-Minute: 3
    < X-RateLimit-Remaining-Minute: 2
    < X-RateLimit-Remaining-Minute: 1
    < X-RateLimit-Remaining-Minute: 1
   

   The policy: local setting in the plugin configuration tracks request counters in each Pod’s local memory separately. Counters are not synchronized across Pods, so clients can send requests past the limit without being throttled if they route through different Pods.

   Using a load balancer that distributes client requests to the same Pod can alleviate this somewhat, but changes to the number of replicas can still disrupt accurate accounting. To consistently enforce the limit, the plugin needs to use a shared set of counters across all Pods. The redis policy can do this when a Redis instance is available.

Deploy Redis to your Kubernetes cluster

Redis provides an external database for Kong components to store shared data, such as rate limiting counters. There are several options to install it:

Bitnami provides a Helm chart for Redis with turnkey options for authentication.

1. Create a password Secret and replace PASSWORD with a password of your choice.

   kubectl create -n kong secret generic redis-password-secret --from-literal=redis-password=PASSWORD
   

   The results should look like this:

   secret/redis-password-secret created
   

2. Install Redis

    helm install -n kong redis oci://registry-1.docker.io/bitnamicharts/redis \
      --set auth.existingSecret=redis-password-secret \
      --set architecture=standalone
   

   Helm displays the instructions that describes the new installation.

3. Update your plugin configuration with the redis policy, Service, and credentials. Replace PASSWORD with the password that you set for Redis.

    kubectl patch kongplugin rate-limit --type json --patch '[
      {
        "op":"replace",
        "path":"/config/policy",
        "value":"redis"
      },
      {
        "op":"add",
        "path":"/config/redis_host",
        "value":"redis-master"
      },
      {
        "op":"add",
        "path":"/config/redis_password",
        "value":"PASSWORD"
      }
    ]'
   

   The results should look like this:

    kongplugin.configuration.konghq.com/rate-limit patched
   

   If the redis_username is not set , it uses the default redis user.

Test rate limiting is a multi-node Kong deployment

Send requests to the Service with rate limiting response headers.

for i in `seq 10`; do curl -sv -H 'Host:kong.example' $PROXY_IP/echo 2>&1 | grep "X-RateLimit-Remaining-Minute"; done

The results should look like this:

< X-RateLimit-Remaining-Minute: 4
< X-RateLimit-Remaining-Minute: 3
< X-RateLimit-Remaining-Minute: 2
< X-RateLimit-Remaining-Minute: 1
< X-RateLimit-Remaining-Minute: 0
< X-RateLimit-Remaining-Minute: 0
< X-RateLimit-Remaining-Minute: 0
< X-RateLimit-Remaining-Minute: 0
< X-RateLimit-Remaining-Minute: 0
< X-RateLimit-Remaining-Minute: 0

The counters decrement sequentially regardless of the Kong Gateway replica count.