For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Rate Limiting

NGINX’s limit-rps and limit-rpm annotations map to a kgateway TrafficPolicy with local rate limiting.

Mapping considerations

Note that the Ingress-NGINX annotation to kgateway TrafficPolicy mapping is not 1:1. The limit-rps/limit-rpm use a shared memory zone keyed by client IP, applying the rate limit per client IP address, per pod. In contrast, the kgateway local token bucket is shared across clients within the scope where the policy is attached (for example, a route), rather than per client IP address.

• Per-client IP address: If you need per-client-IP rate limiting, use global rate limiting with a RemoteAddress descriptor entry (keys on the effective downstream address).
• Forwarded headers: If you need a Header descriptor with X-Forwarded-For, only do so when XFF is validated via trusted-proxy or trusted-hops configuration and normalized to the intended client IP address (for example, the leftmost untrusted hop). Otherwise, clients can spoof or rotate the header and it might include multiple IP addresses.

Before: Ingress with rate limits

cat <<'EOF' > ratelimit-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ratelimit-demo
  annotations:
    nginx.ingress.kubernetes.io/limit-rps: "10"
    nginx.ingress.kubernetes.io/limit-burst-multiplier: "2"
spec:
  ingressClassName: nginx
  rules:
  - host: api.example.com
    http:
      paths:
      - backend:
          service:
            name: api-service
            port:
              number: 8080
        path: /
        pathType: Prefix
EOF

Convert

ingress2gateway print --providers=ingress-nginx --emitter=kgateway \
  --input-file ratelimit-ingress.yaml > ratelimit-kgateway.yaml

After: TrafficPolicy with token bucket

cat ratelimit-kgateway.yaml

The generated TrafficPolicy uses a token bucket algorithm. With 10 RPS and a 2x burst multiplier, you get maxTokens: 20:

apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  name: ratelimit-demo-policy
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: ratelimit-demo-api-example-com
  rateLimit:
    local:
      tokenBucket:
        maxTokens: 20
        tokensPerFill: 10
        fillInterval: 1s

Apply

kubectl apply -f ratelimit-kgateway.yaml