github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.12.0/config/rate-limiting.md (about)

     1  # Rate Limiting
     2  
     3  ## Local Rate Limiting
     4  
     5  The `HTTPProxy` API supports defining local rate limit policies that can be applied to either individual routes or entire virtual hosts.
     6  Local rate limit policies define a maximum number of requests per unit of time that an Envoy should proxy to the upstream service.
     7  Requests beyond the defined limit will receive a `429 (Too Many Requests)` response by default.
     8  Local rate limit policies program Envoy's [HTTP local rate limit filter](https://www.envoyproxy.io/docs/envoy/v1.17.0/configuration/http/http_filters/local_rate_limit_filter#config-http-filters-local-rate-limit).
     9  
    10  It's important to note that local rate limit policies apply *per Envoy pod*.
    11  For example, a local rate limit policy of 100 requests per second for a given route will result in *each Envoy pod* allowing up to 100 requests per second for that route.
    12  
    13  By contrast, **global** rate limiting (which will be added in a future Contour release), uses a shared external rate limit service, allowing rate limits to apply across *all* Envoy pods.
    14  
    15  ### Defining a local rate limit
    16  
    17  Local rate limit policies can be defined for either routes or virtual hosts. A local rate limit policy requires a `requests` and a `units` field, defining the *number of requests per unit of time* that are allowed. `Requests` must be a positive integer, and `units` can be `second`, `minute`, or `hour`. Optionally, a `burst` parameter can also be provided, defining the number of requests above the baseline rate that are allowed in a short period of time. This would allow occasional larger bursts of traffic not to be rate limited.
    18  
    19  Local rate limiting for the virtual host:
    20  ```yaml
    21  apiVersion: projectcontour.io/v1
    22  kind: HTTPProxy
    23  metadata:
    24    namespace: default
    25    name: ratelimited-vhost
    26  spec:
    27    virtualhost:
    28      fqdn: local.projectcontour.io
    29      rateLimitPolicy:
    30      local:
    31        requests: 100
    32        unit: hour
    33        burst: 20
    34    routes:
    35    - conditions:
    36      - prefix: /s1
    37      services:
    38      - name: s1
    39        port: 80
    40    - conditions:
    41      - prefix: /s2
    42      services:
    43      - name: s2
    44        port: 80
    45  ```
    46  
    47  Local rate limiting for the route:
    48  ```yaml
    49  apiVersion: projectcontour.io/v1
    50  kind: HTTPProxy
    51  metadata:
    52    namespace: default
    53    name: ratelimited-route
    54  spec:
    55    virtualhost:
    56      fqdn: local.projectcontour.io
    57    routes:
    58    - conditions:
    59      - prefix: /s1
    60      services:
    61      - name: s1
    62        port: 80
    63      rateLimitPolicy:
    64        local:
    65          requests: 20
    66          unit: minute
    67    - conditions:
    68      - prefix: /s2
    69      services:
    70      - name: s2
    71        port: 80
    72  ```
    73  
    74  ### Customizing the response
    75  
    76  #### Response code
    77  
    78  By default, Envoy returns a `429 (Too Many Requests)` when a request is rate limited.
    79  A non-default response code can optionally be configured as part of the local rate limit policy, in the `responseStatusCode` field.
    80  The value must be in the 400-599 range.
    81  
    82  ```yaml
    83  apiVersion: projectcontour.io/v1
    84  kind: HTTPProxy
    85  metadata:
    86    namespace: default
    87    name: custom-ratelimit-response
    88  spec:
    89    virtualhost:
    90      fqdn: local.projectcontour.io
    91    routes:
    92    - conditions:
    93      - prefix: /s1
    94      services:
    95      - name: s1
    96        port: 80
    97      rateLimitPolicy:
    98        local:
    99          requests: 20
   100          unit: minute
   101          responseStatusCode: 503 # Service Unavailable 
   102  ```
   103  
   104  #### Headers
   105  
   106  Headers can optionally be added to rate limited responses, by configuring the `responseHeadersToAdd` field.
   107  
   108  ```yaml
   109  apiVersion: projectcontour.io/v1
   110  kind: HTTPProxy
   111  metadata:
   112    namespace: default
   113    name: custom-ratelimit-response
   114  spec:
   115    virtualhost:
   116      fqdn: local.projectcontour.io
   117    routes:
   118    - conditions:
   119      - prefix: /s1
   120      services:
   121      - name: s1
   122        port: 80
   123      rateLimitPolicy:
   124        local:
   125          requests: 20
   126          unit: minute
   127          responseHeadersToAdd:
   128          - name: x-contour-ratelimited
   129            value: "true"
   130  ```