| Attachment | Type URL (@type) | Per-route override | Build feature |
|---|---|---|---|
Filter chain (filters) | type.googleapis.com/envoy.extensions.filters.network.ratelimit.v3.RateLimit | Not applicable | None |
What it does
The network rate limit filter calls a rate limit service (RLS) such as envoyproxy/ratelimit over gRPC for every new connection and drops the connection when the service answers over-limit. When the RLS response carries a quota, Arion caches it process-wide for the quota window, so subsequent connections consume a local bucket without a round-trip; one connection refreshes the quota when it expires. Configure it per filter chain, before the terminal filter.
Minimal configuration
From arion-runtime-global-rate-limit.yaml; the fragment sits under filter_chains[].filters:
- name: ratelimit
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.ratelimit.v3.RateLimit
stat_prefix: global_ratelimit
domain: api.example.com
failure_mode_deny: true
descriptors:
- entries:
- key: destination_cluster
value: api
rate_limit_service:
grpc_service:
envoy_grpc:
cluster_name: rlsFields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
stat_prefix | string | Yes | — | Prefix for this filter's statistics. |
domain | string | See note | — | RLS namespace sent with every check. Optional only on listeners with a TLS inspector: when omitted, the connection's TLS SNI becomes the domain, giving each server name its own quota namespace. On listeners without a TLS inspector it is mandatory and startup fails otherwise. |
failure_mode_deny | bool | No | false | Drop the connection when the RLS is unreachable. When false, connections pass on RLS failure. |
descriptors | list | Yes | — | Static descriptors sent with every check; each is a list of {key, value} entries. Dynamic descriptors from connection or request attributes are not supported. |
rate_limit_service.grpc_service | object | Yes | — | The RLS target: envoy_grpc.cluster_name (a cluster speaking HTTP/2) or google_grpc.target_uri, plus an optional timeout. |
A configured domain always wins over the SNI. The top-level Envoy timeout field is unsupported — set the timeout inside grpc_service instead.
Ordering and interactions
At most one rate limit filter per chain, always before the terminal filter. At runtime it fires after the connection limit and before network RBAC. Because the filter chain is selected by SNI first, the limiter is already scoped to the matched tenant when it runs; rejected clients see a closed connection, not an HTTP 429.