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 explicity 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.

FieldTypeDescription
destinationIstioServiceOptional: Destination uniquely identifies the destination service associated with this policy.
sourceIstioServiceOptional: Source uniquely identifies the source service associated with this policy.
loadBalancingLoadBalancingLoad balancing policy.
circuitBreakerCircuitBreakerCircuit breaker policy.
customAny

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
FieldTypeDescription
nameSimpleLBPolicyLoad balancing policy name (as defined in SimpleLBPolicy below)

SimpleLBPolicy

Load balancing algorithms supported by Envoy proxy.

ValueDescription
ROUND_ROBINSimple round robin policy.
LEAST_CONNThe least request load balancer uses an O(1) algorithm which selects two random healthy hosts and picks the host which has fewer active requests.
RANDOMThe 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.

FieldTypeDescription
simpleCbSimpleCircuitBreakerPolicy

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
FieldTypeDescription
maxConnectionsint32Maximum number of connections to a backend.
httpMaxPendingRequestsint32Maximum number of pending requests to a backend. Default 1024
httpMaxRequestsint32Maximum number of requests to a backend. Default 1024
sleepWindowDurationMinimum time the circuit will be closed. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 30s.
httpConsecutiveErrorsint32Number of 5XX errors before circuit is opened. Defaults to 5.
httpDetectionIntervalDurationTime interval between ejection sweep analysis. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.
httpMaxRequestsPerConnectionint32Maximum number of requests per connection to a backend. Setting this parameter to 1 disables keep alive.
httpMaxEjectionPercentint32Maximum % of hosts in the load balancing pool for the destination service that can be ejected by the circuit breaker. Defaults to 10%.