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 ratings service would look as follows:

metadata:
  name: ratings-lb-policy
  namespace: default # optional (default is "default")
spec:
  destination:
    name: ratings
  loadBalancing:
    name: ROUND_ROBIN

The FQDN of the destination service is composed from the destination name and meta namespace fields, along with a platform-specific domain suffix (e.g. on Kubernetes, “reviews” + “default” + “svc.cluster.local” -> “reviews.default.svc.cluster.local”).

A destination policy can be restricted to a particular version of a service or applied to all versions. It can also be restricted to calls from a particular source. For example, the following load balancing policy applies to version v1 of the ratings service running in the prod environment but only when called from version v2 of the reviews service:

metadata:
  name: ratings-lb-policy
  namespace: default
spec:
  source:
    name: reviews
    labels:
      version: v2
  destination:
    name: ratings
    labels:
      env: prod
      version: v1
  loadBalancing:
    name: ROUND_ROBIN

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
destination IstioService Optional: Destination uniquely identifies the destination service associated with this policy.
source IstioService Optional: Source uniquely identifies the source service associated with this policy.
loadBalancing LoadBalancing Load balancing policy.
circuitBreaker CircuitBreaker Circuit breaker policy.
custom Any

LoadBalancing

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

metadata:
  name: reviews-lb-policy
  namespace: default
spec:
  destination:
    name: reviews
  loadBalancing:
    name: RANDOM
Field Type Description
name SimpleLBPolicy Load balancing policy name (as defined in SimpleLBPolicy below)

SimpleLBPolicy

Load balancing algorithms supported by Envoy.

Value Description
ROUND_ROBIN Simple round robin policy.
LEAST_CONN 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 circuit breaker and outlier detection for more details.

Field Type Description
simpleCb SimpleCircuitBreakerPolicy

SimpleCircuitBreakerPolicy

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.

metadata:
  name: reviews-cb-policy
  namespace: default
spec:
  destination:
    name: reviews
    labels:
      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 mins, such that any host that fails 7 consecutive times with 5XX error code will be ejected for 15 minutes.

metadata:
  name: reviews-cb-policy
  namespace: default
spec:
  destination:
    name: reviews
    labels:
      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%.