Rate Limit

New to Kuma? Don’t use this policy, check MeshRateLimit instead.

Rate Limit is an inbound policy. Dataplanes whose configuration is modified are in the destinations matcher.

The RateLimit policy leverages Envoy’s local rate limiting to allow for per-instance service request limiting. All HTTP/HTTP2 based requests are supported.

You can configure how many requests are allowed in a specified time period, and how the service responds when the limit is reached.

The policy is applied per service instance. This means that if a service backend has 3 instances rate limited to 100 requests per second, the overall service is rate limited to 300 requests per second.

When rate limiting to an ExternalService, the policy is applied per sending service instance.`

Usage

  1. apiVersion: kuma.io/v1alpha1
  2. kind: RateLimit
  3. mesh: default
  4. metadata:
  5.   name: rate-limit-all-to-backend
  6. spec:
  7.   sources:
  8.     - match:
  9.         kuma.io/service: "*"
  10.   destinations:
  11.     - match:
  12.         kuma.io/service: backend_default_svc_80
  13.   conf:
  14.     http:
  15.       requests: 5
  16.       interval: 10s
  17.       onRateLimit:
  18.         status: 423
  19.         headers:
  20.           - key: "x-kuma-rate-limited"
  21.             value: "true"
  22.             append: true

Apply the configuration with kubectl apply -f [..].

  1. type: RateLimit
  2. mesh: default
  3. name: rate-limit-all-to-backend
  4. sources:
  5.   - match:
  6.       kuma.io/service: "*"
  7. destinations:
  8.   - match:
  9.       kuma.io/service: backend
  10. conf:
  11.   http:
  12.     requests: 5
  13.     interval: 10s
  14.     onRateLimit:
  15.       status: 423
  16.       headers:
  17.         - key: "x-kuma-rate-limited"
  18.           value: "true"
  19.           append: true

Apply the configuration with kumactl apply -f [..] or with the HTTP API.

Configuration fields

The conf section of the RateLimit resource provides the following configuration options:

  • http -
    • requests - the number of requests to limit
    • interval - the interval for which requests will be limited
    • onRateLimit (optional) - actions to take on RateLimit event
      • status (optional) - the status code to return, defaults to 429
      • headers - list of headers which should be added to every rate limited response:
        • key - the name of the header
        • value - the value of the header
        • append (optional) - should the value of the provided header be appended to already existing headers (if present)

Matching sources

This policy is applied on the destination data plane proxy and generates a set of matching rules for the originating service. These matching rules are ordered from the most specific one, to the more generic ones. Given the following RateLimit resources:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: RateLimit
  3. mesh: default
  4. metadata:
  5.   name: rate-limit-all-to-backend
  6. spec:
  7.   sources:
  8.     - match:
  9.         kuma.io/service: "*"
  10.   destinations:
  11.     - match:
  12.         kuma.io/service: backend_default_svc_80
  13.   conf:
  14.     http:
  15.       requests: 5
  16.       interval: 10s
  17. ---
  18. apiVersion: kuma.io/v1alpha1
  19. kind: RateLimit
  20. mesh: default
  21. metadata:
  22.   name: rate-limit-frontend
  23. spec:
  24.   sources:
  25.     - match:
  26.         kuma.io/service: "frontend_default_svc_80"
  27.   destinations:
  28.     - match:
  29.         kuma.io/service: backend_default_svc_80
  30.   conf:
  31.     http:
  32.       requests: 10
  33.       interval: 10s
  34. ---
  35. apiVersion: kuma.io/v1alpha1
  36. kind: RateLimit
  37. mesh: default
  38. metadata:
  39.   name: rate-limit-frontend-zone-eu
  40. spec:
  41.   sources:
  42.     - match:
  43.         kuma.io/service: "frontend_default_svc_80"
  44.         kuma.io/zone:    "eu"
  45.   destinations:
  46.     - match:
  47.         kuma.io/service: backend_default_svc_80
  48.   conf:
  49.     http:
  50.       requests: 20
  51.       interval: 10s

The service backend is configured with the following rate limiting hierarchy:

  • rate-limit-frontend-zone-eu
  • rate-limit-frontend
  • rate-limit-all-to-backend

Matching destinations

RateLimit, when applied to a dataplane proxy bound Kuma service, is an Inbound Connection Policy.

When applied to an ExternalService, RateLimit is an Outbound Connection Policy. In this case, the only supported value for destinations.match is kuma.io/service.

Builtin Gateway support

Kuma Gateway supports the RateLimit connection policy. Rate limits are configured on each Envoy route by selecting the best Rate Limit policy that matches the source and destination.

All options