Admission Control

This extension has the qualified name envoy.filters.http.admission_control

Note

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

extensions.filters.http.admission_control.v3.AdmissionControl

[extensions.filters.http.admission_control.v3.AdmissionControl proto]

{
  "enabled": "{...}",
  "success_criteria": "{...}",
  "sampling_window": "{...}",
  "aggression": "{...}",
  "sr_threshold": "{...}",
  "rps_threshold": "{...}",
  "max_rejection_probability": "{...}"
}
enabled

(config.core.v3.RuntimeFeatureFlag) If set to false, the admission control filter will operate as a pass-through filter. If the message is unspecified, the filter will be enabled.

success_criteria

(extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria, REQUIRED) Defines how a request is considered a success/failure.

sampling_window

(Duration) The sliding time window over which the success rate is calculated. The window is rounded to the nearest second. Defaults to 30s.

aggression

(config.core.v3.RuntimeDouble) Rejection probability is defined by the formula:

max(0, (rq_count -  rq_success_count / sr_threshold) / (rq_count + 1)) ^ (1 / aggression)

The aggression dictates how heavily the admission controller will throttle requests upon SR dropping at or below the threshold. A value of 1 will result in a linear increase in rejection probability as SR drops. Any values less than 1.0, will be set to 1.0. If the message is unspecified, the aggression is 1.0. See the admission control documentation for a diagram illustrating this.

sr_threshold

(config.core.v3.RuntimePercent) Dictates the success rate at which the rejection probability is non-zero. As success rate drops below this threshold, rejection probability will increase. Any success rate above the threshold results in a rejection probability of 0. Defaults to 95%.

rps_threshold

(config.core.v3.RuntimeUInt32) If the average RPS of the sampling window is below this threshold, the request will not be rejected, even if the success rate is lower than sr_threshold. Defaults to 0.

max_rejection_probability

(config.core.v3.RuntimePercent) The probability of rejection will never exceed this value, even if the failure rate is rising. Defaults to 80%.

extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria

[extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria proto]

Default method of specifying what constitutes a successful request. All status codes that indicate a successful request must be explicitly specified if not relying on the default values.

{
  "http_criteria": "{...}",
  "grpc_criteria": "{...}"
}
http_criteria

(extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria.HttpCriteria) If HTTP criteria are unspecified, all HTTP status codes below 500 are treated as successful responses.

Note

The default HTTP codes considered successful by the admission controller are done so due to the unlikelihood that sending fewer requests would change their behavior (for example: redirects, unauthorized access, or bad requests won’t be alleviated by sending less traffic).

grpc_criteria

(extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria.GrpcCriteria) GRPC status codes to consider as request successes. If unspecified, defaults to: Ok, Cancelled, Unknown, InvalidArgument, NotFound, AlreadyExists, Unauthenticated, FailedPrecondition, OutOfRange, PermissionDenied, and Unimplemented.

Note

The default gRPC codes that are considered successful by the admission controller are chosen because of the unlikelihood that sending fewer requests will change the behavior.

extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria.HttpCriteria

[extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria.HttpCriteria proto]

{
  "http_success_status": []
}
http_success_status

(repeated type.v3.Int32Range, REQUIRED) Status code ranges that constitute a successful request. Configurable codes are in the range [100, 600).

extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria.GrpcCriteria

[extensions.filters.http.admission_control.v3.AdmissionControl.SuccessCriteria.GrpcCriteria proto]

{
  "grpc_success_status": []
}
grpc_success_status

(repeated uint32, REQUIRED) Status codes that constitute a successful request. Mappings can be found at: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md.