Circuit breakers¶

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

api/v2/cluster/circuit_breaker.proto

config.cluster.v3.CircuitBreakers¶

[config.cluster.v3.CircuitBreakers proto]

Circuit breaking settings can be specified individually for each defined priority.

{
  "thresholds": [],
  "per_host_thresholds": []
}

thresholds: (repeated config.cluster.v3.CircuitBreakers.Thresholds) If multiple Thresholds are defined with the same RoutingPriority, the first one in the list is used. If no Thresholds is defined for a given RoutingPriority, the default values are used.

per_host_thresholds

(repeated config.cluster.v3.CircuitBreakers.Thresholds) Optional per-host limits which apply to each individual host in a cluster.

Note

currently only the max_connections field is supported for per-host limits.

If multiple per-host Thresholds are defined with the same RoutingPriority, the first one in the list is used. If no per-host Thresholds are defined for a given RoutingPriority, the cluster will not have per-host limits.

config.cluster.v3.CircuitBreakers.Thresholds¶

[config.cluster.v3.CircuitBreakers.Thresholds proto]

A Thresholds defines CircuitBreaker settings for a RoutingPriority.

{
  "priority": "...",
  "max_connections": "{...}",
  "max_pending_requests": "{...}",
  "max_requests": "{...}",
  "max_retries": "{...}",
  "retry_budget": "{...}",
  "track_remaining": "...",
  "max_connection_pools": "{...}"
}

priority: (config.core.v3.RoutingPriority) The RoutingPriority the specified CircuitBreaker settings apply to.

max_connections: (UInt32Value) The maximum number of connections that Envoy will make to the upstream cluster. If not specified, the default is 1024.

max_pending_requests: (UInt32Value) The maximum number of pending requests that Envoy will allow to the upstream cluster. If not specified, the default is 1024. This limit is applied as a connection limit for non-HTTP traffic.

max_requests: (UInt32Value) The maximum number of parallel requests that Envoy will make to the upstream cluster. If not specified, the default is 1024. This limit does not apply to non-HTTP traffic.

max_retries: (UInt32Value) The maximum number of parallel retries that Envoy will allow to the upstream cluster. If not specified, the default is 3.

retry_budget: (config.cluster.v3.CircuitBreakers.Thresholds.RetryBudget) Specifies a limit on concurrent retries in relation to the number of active requests. This parameter is optional.

Note

If this field is set, the retry budget will override any configured retry circuit breaker.

track_remaining: (bool) If track_remaining is true, then stats will be published that expose the number of resources remaining until the circuit breakers open. If not specified, the default is false.

Note

If a retry budget is used in lieu of the max_retries circuit breaker, the remaining retry resources remaining will not be tracked.

max_connection_pools: (UInt32Value) The maximum number of connection pools per cluster that Envoy will concurrently support at once. If not specified, the default is unlimited. Set this for clusters which create a large number of connection pools. See Circuit Breaking for more details.

config.cluster.v3.CircuitBreakers.Thresholds.RetryBudget¶

[config.cluster.v3.CircuitBreakers.Thresholds.RetryBudget proto]

{
  "budget_percent": "{...}",
  "min_retry_concurrency": "{...}"
}

budget_percent

(type.v3.Percent) Specifies the limit on concurrent retries as a percentage of the sum of active requests and active pending requests. For example, if there are 100 active requests and the budget_percent is set to 25, there may be 25 active retries.

This parameter is optional. Defaults to 20%.

min_retry_concurrency

(UInt32Value) Specifies the minimum retry concurrency allowed for the retry budget. The limit on the number of active retries may never go below this number.

This parameter is optional. Defaults to 3.