Rate Limiting

This configuration guide shows how to limit the number of requests handled by Airlock Microgateway using the rate limit filter.

Rate limiting is configured with a RateLimitPolicy. The policy is attached directly to an HTTPRoute and defines one or more rate limit policies for the routed traffic. Rate limits can apply to the entire route, to selected requests based on request conditions, or separately per client IP.

Prerequisites

A Gateway Deployment.
An HTTPRoute routing traffic to your application.

Configuration

Limit all requests on a route

Create a RateLimitPolicy in the same namespace as the HTTPRoute that you want to attach it to.

The following example limits all requests on the referenced HTTPRoute to 1000 requests per second.

Example

apiVersion: microgateway.airlock.com/v1alpha1
kind: RateLimitPolicy
metadata:
  name: <your-rate-limit-policy-name>
  namespace: <your-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: <your-httproute-name>
  policies:
    - rateLimitHeaders: DraftVersion3
      local:
        limit:
          requests: 1000

Because no requestConditions are configured, the policy applies to all requests on the route. When the configured rate is exceeded, Airlock Microgateway blocks further requests according to the default threat handling mode.

Configure multiple limits and an exception

Use multiple policy entries to apply different limits to different request paths.

The following example configures different limits and an exception:

Requests to /app1 that exceed 100 requests per second are logged only.
Requests to /app2 are limited to 300 requests per second.
Requests to /unlimited are not rate limited.
All other requests are limited to 1000 requests per second.

Example

apiVersion: microgateway.airlock.com/v1alpha1
kind: RateLimitPolicy
metadata:
  name: <your-rate-limit-policy-name>
  namespace: <your-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: <your-httproute-name>
  policies:
    - requestConditions:
        path:
          matcher:
            prefix: /app1
      threatHandlingMode: LogOnly
      local:
        limit:
          requests: 100

    - requestConditions:
        path:
          matcher:
            prefix: /app2
      local:
        limit:
          requests: 300

    - requestConditions:
        path:
          matcher:
            prefix: /unlimited

    - rateLimitHeaders: DraftVersion3
      local:
        limit:
          requests: 1000

Place more specific policies before the default policy.

Policy order matters because the first matching policy applies. Therefore, the path-specific policies for /app1, /app2, and /unlimited must be listed before the default policy. The /unlimited policy does not define a local rate limit, so matching requests are not counted by the rate limiter and do not fall through to the default rate limit.

The final policy has no requestConditions and therefore acts as the default policy for all requests that did not match an earlier policy.

Count requests per client IP

Use countBy.ip to apply the configured rate limit separately per client IP.

The following example limits the route to 1000 requests per second per client IP:

Example

apiVersion: microgateway.airlock.com/v1alpha1
kind: RateLimitPolicy
metadata:
  name: <your-rate-limit-policy-name>
  namespace: <your-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: <your-httproute-name>
  policies:
    - rateLimitHeaders: DraftVersion3
      local:
        limit:
          requests: 1000
      countBy:
        ip:
          numberOfCounters: 10000

Use numberOfCounters to limit the number of distinct client IP addresses tracked by the policy and to prevent unbounded memory usage. If the number of distinct client IPs exceeds the maximum of 10000, the oldest IP counter is discarded.

Set rateLimitHeaders: DraftVersion3 to make Airlock Microgateway write rate-limit response headers according to draft version 3 of the HTTP RateLimit header specification.

Validation

After applying the RateLimitPolicy, verify that it has been accepted by the targeted resource by checking that the Accepted condition in status.ancestors[].conditions has status True.

If rateLimitHeaders: DraftVersion3 is configured, send a request to a path covered by the policy and check the response headers. The X-RateLimit-* headers make the current rate limit state visible on the client side.

You can also use metrics to observe rate limiting behavior. Check the ratelimited_requests_total metric to see whether requests are being rate-limited.

Rate limit memory considerations

Each policy with a configured rate limit uses memory to count requests. For simple counters, the additional memory usage is usually negligible.

For rate limits that count requests per IP, memory usage requires more attention. In this case, Airlock Microgateway keeps separate counters in memory for the tracked client IP addresses.

Use countBy.ip.numberOfCounters to restrict the maximum number of IP counters. When this maximum is exceeded, the Engine forgets the least current counter.

Choose the value carefully:

If numberOfCounters is too low, an attacker with enough source IP addresses may bypass the rate limit.
If numberOfCounters is too high, memory usage may become problematic.

As a rough estimate, assume that one per-IP counter requires about 500 bytes of additional memory.

Example:

Example

Baseline memory usage: 8 MB
Number of counted IPs: 10000
Estimated memory usage: 8 MB + 10000 * 500 bytes = 13 MB

CR reference documentation

CR RateLimitPolicy