Admission Control
See the v3 API reference for details on each configuration parameter.
Overview
The admission control filter probabilistically rejects requests based on the success rate of previous requests in a configurable sliding time window. It is based on client-side throttling from the Google SRE handbook. The only notable difference between the admission control filter’s load shedding and load shedding defined in client-side throttling is that users may configure how aggressively load shedding starts at a target request success rate. Users may also configure the definition of a successful request for the purposes of the rejection probability calculation.
The probability that the filter will reject a request is as follows:
where,
n refers to a request count gathered in the sliding window.
threshold is a configurable value that dictates the lowest request success rate at which the filter will not reject requests. The value is normalized to [0,1] for the calculation.
aggression controls the rejection probability curve such that 1.0 is a linear increase in rejection probability as the success rate decreases. As the aggression increases, the rejection probability will be higher for higher success rates. See Aggression for a more detailed explanation.
Note that there are additional parameters that affect the rejection probability:
rps_threshold is a configurable value that when RPS is lower than it, requests will pass through the filter.
max_reject_probability represents the upper limit of the rejection probability.
Note
The success rate calculations are performed on a per-thread basis for increased performance. In addition, the per-thread isolation prevents decreases the blast radius of a single bad connection with an anomalous success rate. Therefore, the rejection probability may vary between worker threads.
Note
Health check traffic does not count towards any of the filter’s measurements.
Note
Only non-route-specific virtual host configurations are supported.
See the v3 API reference for more details on this parameter.
The definition of a successful request is a configurable parameter for both HTTP and gRPC requests.
Aggression
The aggression value affects the rejection probabilities as shown in the following figures:
Since the success rate threshold in the first figure is set to 95%, the rejection probability remains 0 until then. In the second figure, there rejection probability remains 0 until the success rate reaches 50%. In both cases, as success rate drops to 0%, the rejection probability approaches a value just under 100%. The aggression values dictate how high the rejection probability will be at a given request success rate, so it will shed load more aggressively.
Example Configuration
An example filter configuration can be found below. Not all fields are required and many of the fields can be overridden via runtime settings.
1 typed_config:
2 '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
3 stat_prefix: ingress_http
4 http_filters:
5 - name: envoy.filters.http.admission_control
6 typed_config:
7 '@type': type.googleapis.com/envoy.extensions.filters.http.admission_control.v3.AdmissionControl
8 enabled:
9 default_value: true
10 runtime_key: admission_control.enabled
11 sampling_window: 60s
12 sr_threshold:
13 default_value:
14 value: 95.0
15 runtime_key: admission_control.sr_threshold
16 aggression:
17 default_value: 1.0
18 runtime_key: admission_control.aggression
19 rps_threshold:
20 default_value: 1
21 runtime_key: admission_control.rps_threshold
22 max_rejection_probability:
23 default_value:
24 value: 95.0
25 runtime_key: admission_control.max_rejection_probability
26 success_criteria:
27 http_criteria:
28 http_success_status:
29 - start: 100
30 end: 400
31 - start: 404
32 end: 404
33 grpc_criteria:
34 grpc_success_status:
35 - 0
36 - 1
37 - name: envoy.filters.http.router
38 typed_config:
39 '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
40 route_config:
41 name: local_route
42 virtual_hosts:
43 - domains:
44 - '*'
45 name: local_service
46 routes:
47 - match: { prefix: "/" }
48 route: { cluster: default_service }
The above configuration can be understood as follows:
Calculate the request success-rate over a 120s sliding window.
Do not begin shedding any load until the request success-rate drops below 95% in the sliding window.
HTTP requests are considered successful if they are 1xx, 2xx, 3xx, or a 404.
gRPC requests are considered successful if they are OK or CANCELLED.
Requests will never be rejected from this filter if the RPS is lower than 5.
Rejection probability will never exceed 80% even if the failure rate is 100%.
Statistics
The admission control filter outputs statistics in the http.<stat_prefix>.admission_control. namespace. The stat prefix comes from the owning HTTP connection manager.
Name |
Type |
Description |
---|---|---|
rq_rejected |
Counter |
Total requests that were not admitted by the filter. |
rq_success |
Counter |
Total requests that were considered a success. |
rq_failure |
Counter |
Total requests that were considered a failure. |