.. _config_http_filters_local_rate_limit: Local rate limit ================ * Local rate limiting :ref:`architecture overview ` * :ref:`v3 API reference ` * This filter should be configured with the name *envoy.filters.http.local_ratelimit*. The HTTP local rate limit filter applies a :ref:`token bucket ` rate limit when the request's route or virtual host has a per filter :ref:`local rate limit configuration `. If the local rate limit token bucket is checked, and there are no token availables, a 429 response is returned (the response is configurable). The local rate limit filter also sets the :ref:`x-envoy-ratelimited` header. Additional response headers may be configured. .. note:: The token bucket is shared across all workers, thus the rate limits are applied per Envoy process. Example configuration --------------------- Example filter configuration for a globally set rate limiter (e.g.: all vhosts/routes share the same token bucket): .. code-block:: yaml name: envoy.filters.http.local_ratelimit typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit stat_prefix: http_local_rate_limiter token_bucket: max_tokens: 10000 tokens_per_fill: 1000 fill_interval: 1s filter_enabled: runtime_key: local_rate_limit_enabled default_value: numerator: 100 denominator: HUNDRED filter_enforced: runtime_key: local_rate_limit_enforced default_value: numerator: 100 denominator: HUNDRED response_headers_to_add: - append: false header: key: x-local-rate-limit value: 'true' Example filter configuration for a globally disabled rate limiter but enabled for a specific route: .. code-block:: yaml name: envoy.filters.http.local_ratelimit typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit stat_prefix: http_local_rate_limiter The route specific configuration: .. code-block:: yaml route_config: name: local_route virtual_hosts: - name: local_service domains: ["*"] routes: - match: { prefix: "/path/with/rate/limit" } route: { cluster: service_protected_by_rate_limit } typed_per_filter_config: envoy.filters.http.local_ratelimit: "@type": type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit token_bucket: max_tokens: 10000 tokens_per_fill: 1000 fill_interval: 1s filter_enabled: runtime_key: local_rate_limit_enabled default_value: numerator: 100 denominator: HUNDRED filter_enforced: runtime_key: local_rate_limit_enforced default_value: numerator: 100 denominator: HUNDRED response_headers_to_add: - append: false header: key: x-local-rate-limit value: 'true' - match: { prefix: "/" } route: { cluster: default_service } Note that if this filter is configured as globally disabled and there are no virtual host or route level token buckets, no rate limiting will be applied. Statistics ---------- The local rate limit filter outputs statistics in the *.http_local_rate_limit.* namespace. 429 responses -- or the configured status code -- are emitted to the normal cluster :ref:`dynamic HTTP statistics `. .. csv-table:: :header: Name, Type, Description :widths: 1, 1, 2 enabled, Counter, Total number of requests for which the rate limiter was consulted ok, Counter, Total under limit responses from the token bucket rate_limited, Counter, Total responses without an available token (but not necessarily enforced) enforced, Counter, Total number of requests for which rate limiting was applied (e.g.: 429 returned) .. _config_http_filters_local_rate_limit_runtime: Runtime ------- The HTTP rate limit filter supports the following runtime fractional settings: http_filter_enabled % of requests that will check the local rate limit decision, but not enforce, for a given *route_key* specified in the :ref:`local rate limit configuration `. Defaults to 0. http_filter_enforcing % of requests that will enforce the local rate limit decision for a given *route_key* specified in the :ref:`local rate limit configuration `. Defaults to 0. This can be used to test what would happen before fully enforcing the outcome.