Rate Limit

Overview

The Rate Limit Traffic Policy action enables you to configure thresholds that restrict the throughput of traffic that successfully reaches your endpoint.

Traffic may be limited overall or by attributes of the incoming requests.

Configuration Reference

The Traffic Policy configuration reference for this action.

Supported Phases

on_http_request, on_http_response

Type

rate-limit

Configuration Fields

• namestringRequired

  A name for this rate limit configuration. Must be less than 1024 characters.

• algorithmenumRequired

  The rate limit algorithm to be used.

  • Supported values
  • sliding_window

• capacityintegerRequired

  The maximum number of requests allowed to reach your upstream server.

  The minimum capacity is 1 and the maximum capacity is 2,000,000,000.

• ratestringRequired

  The duration in which events may be limited based on the current capacity. Must be specified as a time duration that is a multiple of ten seconds (e.g., "90s", "10m").

  The minimum value is "60s" and the maximum value is "24h".

• bucket_keyarray of stringsRequired

  The elements of this collection define the unique key of a request to track the rate at which the capacity is being met.

  • Supported values
  • req.host - The Host of the request.
  • conn.client_ip - The client IP address.
  • req.headers['x-example-header-name'] - The value for the specified header key, if it exists.
  • getReqHeader('X-Example-Header-Name') - The value for the specified header key, if it exists.

  Up to ten bucket keys can be specified.

Behavior

Determining the Rate Limit Bucket

When this action is executed, information from the incoming HTTP request is used to determine which rate limit bucket the request falls into. Each bucket is defined by specific criteria through the bucket_key configuration field such as client IP, request host, or a header value.

If the bucket has not exceeded its capacity, the request proceeds to the next action in your policy configuration.

Rate Limit Exceeded

If the identified bucket has received more events than its capacity over the specified duration:

1. The request is rejected with an HTTP 429 — Too Many Requests status code.
2. The retry-after header is included in the response, indicating the number of seconds after which the request may be retried.

Capacity per Ingress Server

Currently, the capacity for each rate limit bucket is applied per ingress server. This means that each server independently tracks the number of requests and enforces the rate limits accordingly.

Examples

Rate Limit by Host Header

The following Traffic Policy configuration demonstrates how to use the rate-limit action to rate limit all incoming requests by the Host header.

Example Traffic Policy Document

YAML

---
on_http_request:
  - actions:
      - type: rate-limit
        config:
          name: Only allow 30 requests per minute
          algorithm: sliding_window
          capacity: 30
          rate: 60s
          bucket_key:
            - req.headers['host']

JSON

{
  "on_http_request": [
    {
      "actions": [
        {
          "type": "rate-limit",
          "config": {
            "name": "Only allow 30 requests per minute",
            "algorithm": "sliding_window",
            "capacity": 30,
            "rate": "60s",
            "bucket_key": [
              "req.headers['host']"
            ]
          }
        }
      ]
    }
  ]
}

For this example, we are assuming that ngrok is pointing at the upstream service https://httpbin.org.

Example Request

$ curl https://httpbin.ngrok.app/get

HTTP/2 429
retry-after: 24

In this example, we attempt to connect to httpbin.ngrok.app using the curl command and get back a 429 status code with a retry-after header telling us the number of seconds we must wait before retrying the request.

Action Result Variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

• actions.ngrok.rate_limit.bucket_keystring

  The key used for bucketing requests. This is the key used to group and track requests in the rate-limiting process, ensuring that the same bucket is subject to the rate limit across multiple requests.

• actions.ngrok.rate_limit.limitedboolean

  Indicates whether the request was limited by the rate limit. If true, the request was rate-limited based on the configured limits for the specified bucket.

• actions.ngrok.rate_limit.error.codestring

  A machine-readable code describing an error that occurred during the action's execution.

• actions.ngrok.rate_limit.error.messagestring

  A human-readable message providing details about an error that occurred during the action's execution.