Destination Policies

DestinationPolicy

DestinationPolicy defines client/caller-side policies that determine how to handle traffic bound to a particular destination service. The policy specifies configuration for load balancing and circuit breakers. For example, a simple load balancing policy for the reviews service would look as follows:

destination: reviews.default.svc.cluster.local
policy:
- loadBalancing: 
    name: RANDOM
  simpleCb:
    maxConnections: 1000

Policies are applicable per individual service versions. ONLY ONE policy can be defined per service version. Policy CANNOT be empty.

Field	Type	Description
`destination`	string	REQUIRED. Service name for which the service version is defined. The value MUST BE a fully-qualified domain name, e.g. my-service.default.svc.cluster.local.
`policy[]`	repeated DestinationVersionPolicy	REQUIRED. List of policies, one per service version.

DestinationVersionPolicy

A destination policy can be restricted to a particular version of a service or applied to all versions. The tags field in the DestinationVersionPolicy allow restricting the scope of a DestinationPolicy. For example, the following load balancing policy applies to version v1 of the reviews service running in the prod environment:

destination: reviews.default.svc.cluster.local
policy:
- tags:
    env: prod
    version: v1
  loadBalancing: 
    name: RANDOM

If tags are omitted, the policy applies for all versions of the service. Policy CANNOT BE empty. Note: Destination policies will be applied only if the corresponding tagged instances are explicitly routed to. In other words, for every destination policy defined, at least one route rule must refer to the service version indicated in the destination policy.

Field	Type	Description
`tags`	repeated map<string, string>	Optional set of tags that identify a particular version of the destination service. If omitted, the policy will apply to all versions of the service.
`loadBalancing`	LoadBalancing	Load balancing policy.
`circuitBreaker`	CircuitBreaker	Circuit breaker policy.

LoadBalancing

Load balancing policy to use when forwarding traffic. These policies directly correlate to load balancer types supported by Envoy. Example,

destination: reviews.default.svc.cluster.local
policy:
- loadBalancing: 
    name: RANDOM

Field	Type	Description
`name`	SimpleLBPolicy	Load balancing policy name (as defined in SimpleLBPolicy below)

SimpleLBPolicy

Load balancing algorithms supported by Envoy proxy.

Value	Description
ROUNDROBIN	Simple round robin policy.
LEASTCONN	The least request load balancer uses an O(1) algorithm which selects two random healthy hosts and picks the host which has fewer active requests.
RANDOM	The random load balancer selects a random healthy host. The random load balancer generally performs better than round robin if no health checking policy is configured.

CircuitBreaker

Circuit breaker configuration for Envoy. The circuit breaker implementation is fine-grained in that it tracks the success/failure rates of individual hosts in the load balancing pool. Hosts that continually return errors for API calls are ejected from the pool for a pre-defined period of time. See Envoy’s outlier detection for more details.

Field	Type	Description
`simpleCb`	SimpleCircuitBreakerPolicy

SimpleCircuitBreakerPolicy

Parameters to tune Envoy’s circuit breaker configuration. A simple circuit breaker can be set based on a number of criteria such as connection and request limits. For example, the following destination policy sets a limit of 100 connections to “reviews” service version “v1” backends.

destination: reviews.default.svc.cluster.local
policy:
- tags:
    version: v1
  circuitBreaker:
    simpleCb:
      maxConnections: 100

The following destination policy sets a limit of 100 connections and 1000 concurrent requests, with no more than 10 req/connection to “reviews” service version “v1” backends. In addition, it configures hosts to be scanned every 5 minutes, such that any host that fails 7 consecutive times with 5XX error code will be ejected for 15 minutes.

destination: reviews.default.svc.cluster.local
policy:
- tags:
    version: v1
  circuitBreaker:
    simpleCb:
      maxConnections: 100
      httpMaxRequests: 1000
      httpMaxRequestsPerConnection: 10
      httpConsecutiveErrors: 7
      sleepWindow: 15m
      httpDetectionInterval: 5m

Field	Type	Description
`maxConnections`	int32	Maximum number of connections to a backend.
`httpMaxPendingRequests`	int32	Maximum number of pending requests to a backend. Default 1024
`httpMaxRequests`	int32	Maximum number of requests to a backend. Default 1024
`sleepWindow`	Duration	Minimum time the circuit will be closed. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 30s.
`httpConsecutiveErrors`	int32	Number of 5XX errors before circuit is opened. Defaults to 5.
`httpDetectionInterval`	Duration	Time interval between ejection sweep analysis. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.
`httpMaxRequestsPerConnection`	int32	Maximum number of requests per connection to a backend. Setting this parameter to 1 disables keep alive.
`httpMaxEjectionPercent`	int32	Maximum % of hosts in the load balancing pool for the destination service that can be ejected by the circuit breaker. Defaults to 10%.