Destination Rule

DestinationRule defines policies that apply to traffic intended for aservice after routing has occurred. These rules specify configurationfor load balancing, connection pool size from the sidecar, and outlierdetection settings to detect and evict unhealthy hosts from the loadbalancing pool. For example, a simple load balancing policy for theratings service would look as follows:

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: bookinfo-ratings
  5. spec:
  6. host: ratings.prod.svc.cluster.local
  7. trafficPolicy:
  8. loadBalancer:
  9. simple: LEAST_CONN

Version specific policies can be specified by defining a namedsubset and overriding the settings specified at the service level. Thefollowing rule uses a round robin load balancing policy for all trafficgoing to a subset named testversion that is composed of endpoints (e.g.,pods) with labels (version:v3).

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: bookinfo-ratings
  5. spec:
  6. host: ratings.prod.svc.cluster.local
  7. trafficPolicy:
  8. loadBalancer:
  9. simple: LEAST_CONN
  10. subsets:
  11. - name: testversion
  12. labels:
  13. version: v3
  14. trafficPolicy:
  15. loadBalancer:
  16. simple: ROUND_ROBIN

Note: Policies specified for subsets will not take effect untila route rule explicitly sends traffic to this subset.

Traffic policies can be customized to specific ports as well. Thefollowing rule uses the least connection load balancing policy for alltraffic to port 80, while uses a round robin load balancing setting fortraffic to the port 9080.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: bookinfo-ratings-port
  5. spec:
  6. host: ratings.prod.svc.cluster.local
  7. trafficPolicy: # Apply to all ports
  8. portLevelSettings:
  9. - port:
  10. number: 80
  11. loadBalancer:
  12. simple: LEAST_CONN
  13. - port:
  14. number: 9080
  15. loadBalancer:
  16. simple: ROUND_ROBIN

ConnectionPoolSettings

Connection pool settings for an upstream host. The settings apply toeach individual host in the upstream service. See Envoy’s circuitbreakerfor more details. Connection pool settings can be applied at the TCPlevel as well as at HTTP level.

For example, the following rule sets a limit of 100 connections to redisservice called myredissrv with a connect timeout of 30ms

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: bookinfo-redis
  5. spec:
  6. host: myredissrv.prod.svc.cluster.local
  7. trafficPolicy:
  8. connectionPool:
  9. tcp:
  10. maxConnections: 100
  11. connectTimeout: 30ms
  12. tcpKeepalive:
  13. time: 7200s
  14. interval: 75s
FieldTypeDescriptionRequired
tcpTCPSettings
Settings common to both HTTP and TCP upstream connections.
No
httpHTTPSettings
HTTP connection pool settings.
No

ConnectionPoolSettings.HTTPSettings

Settings applicable to HTTP1.1/HTTP2/GRPC connections.

FieldTypeDescriptionRequired
http1MaxPendingRequestsint32
Maximum number of pending HTTP requests to a destination. Default 2^32-1.
No
http2MaxRequestsint32
Maximum number of requests to a backend. Default 2^32-1.
No
maxRequestsPerConnectionint32
Maximum number of requests per connection to a backend. Setting thisparameter to 1 disables keep alive. Default 0, meaning “unlimited”,up to 2^29.
No
maxRetriesint32
Maximum number of retries that can be outstanding to all hosts in acluster at a given time. Defaults to 2^32-1.
No
idleTimeoutDuration
The idle timeout for upstream connection pool connections. The idle timeout is defined as the period in which there are no active requests.If not set, the default is 1 hour. When the idle timeout is reached the connection will be closed.Note that request based timeouts mean that HTTP/2 PINGs will not keep the connection alive. Applies to both HTTP1.1 and HTTP2 connections.
No
h2UpgradePolicyH2UpgradePolicy
Specify if http1.1 connection should be upgraded to http2 for the associated destination.
No

ConnectionPoolSettings.HTTPSettings.H2UpgradePolicy

Policy for upgrading http1.1 connections to http2.

NameDescription
DEFAULT
Use the global default.
DO_NOT_UPGRADE
Do not upgrade the connection to http2.This opt-out option overrides the default.
UPGRADE
Upgrade the connection to http2.This opt-in option overrides the default.

ConnectionPoolSettings.TCPSettings

Settings common to both HTTP and TCP upstream connections.

FieldTypeDescriptionRequired
maxConnectionsint32
Maximum number of HTTP1 /TCP connections to a destination host. Default 2^32-1.
No
connectTimeoutDuration
TCP connection timeout.
No
tcpKeepaliveTcpKeepalive
If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.
No

ConnectionPoolSettings.TCPSettings.TcpKeepalive

TCP keepalive.

FieldTypeDescriptionRequired
probesuint32
Maximum number of keepalive probes to send without response beforedeciding the connection is dead. Default is to use the OS level configuration(unless overridden, Linux defaults to 9.)
No
timeDuration
The time duration a connection needs to be idle before keep-aliveprobes start being sent. Default is to use the OS level configuration(unless overridden, Linux defaults to 7200s (ie 2 hours.)
No
intervalDuration
The time duration between keep-alive probes.Default is to use the OS level configuration(unless overridden, Linux defaults to 75s.)
No

DestinationRule

DestinationRule defines policies that apply to traffic intended for a serviceafter routing has occurred.

FieldTypeDescriptionRequired
hoststring
The name of a service from the service registry. Servicenames are looked up from the platform’s service registry (e.g.,Kubernetes services, Consul services, etc.) and from the hostsdeclared by ServiceEntries. Rules defined forservices that do not exist in the service registry will be ignored.

Note for Kubernetes users: When short names are used (e.g. “reviews”instead of “reviews.default.svc.cluster.local”), Istio will interpretthe short name based on the namespace of the rule, not the service. Arule in the “default” namespace containing a host “reviews” will beinterpreted as “reviews.default.svc.cluster.local”, irrespective ofthe actual namespace associated with the reviews service. To avoidpotential misconfigurations, it is recommended to always use fullyqualified domain names over short names.

Note that the host field applies to both HTTP and TCP services.
Yes
trafficPolicyTrafficPolicy
Traffic policies to apply (load balancing policy, connection poolsizes, outlier detection).
No
subsetsSubset[]
One or more named sets that represent individual versions of aservice. Traffic policies can be overridden at subset level.
No
exportTostring[]
A list of namespaces to which this destination rule is exported.The resolution of a destination rule to apply to a service occurs in thecontext of a hierarchy of namespaces. Exporting a destination rule allowsit to be included in the resolution hierarchy for services inother namespaces. This feature provides a mechanism for service ownersand mesh administrators to control the visibility of destination rulesacross namespace boundaries.

If no namespaces are specified then the destination rule is exported to allnamespaces by default.

The value “.” is reserved and defines an export to the same namespace thatthe destination rule is declared in. Similarly, the value “” is reserved anddefines an export to all namespaces.

NOTE: in the current release, the exportTo value is restricted to“.” or “
” (i.e., the current namespace or all namespaces).
No

LoadBalancerSettings

Load balancing policies to apply for a specific destination. See Envoy’sload balancingdocumentationfor more details.

For example, the following rule uses a round robin load balancing policyfor all traffic going to the ratings service.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: bookinfo-ratings
  5. spec:
  6. host: ratings.prod.svc.cluster.local
  7. trafficPolicy:
  8. loadBalancer:
  9. simple: ROUND_ROBIN

The following example sets up sticky sessions for the ratings servicehashing-based load balancer for the same ratings service using thethe User cookie as the hash key.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: bookinfo-ratings
  5. spec:
  6. host: ratings.prod.svc.cluster.local
  7. trafficPolicy:
  8. loadBalancer:
  9. consistentHash:
  10. httpCookie:
  11. name: user
  12. ttl: 0s
FieldTypeDescriptionRequired
simpleSimpleLB (oneof)Yes
consistentHashConsistentHashLB (oneof)Yes
localityLbSettingLocalityLoadBalancerSetting
Locality load balancer settings, this will override mesh wide settings in entirety, meaning no merging would be performedbetween this object and the object one in MeshConfig
No

LoadBalancerSettings.ConsistentHashLB

Consistent Hash-based load balancing can be used to provide softsession affinity based on HTTP headers, cookies or otherproperties. This load balancing policy is applicable only for HTTPconnections. The affinity to a particular destination host will belost when one or more hosts are added/removed from the destinationservice.

FieldTypeDescriptionRequired
httpHeaderNamestring (oneof)
Hash based on a specific HTTP header.
Yes
httpCookieHTTPCookie (oneof)
Hash based on HTTP cookie.
Yes
useSourceIpbool (oneof)
Hash based on the source IP address.
Yes
minimumRingSizeuint64
The minimum number of virtual nodes to use for the hashring. Defaults to 1024. Larger ring sizes result in more granularload distributions. If the number of hosts in the load balancingpool is larger than the ring size, each host will be assigned asingle virtual node.
No

LoadBalancerSettings.ConsistentHashLB.HTTPCookie

Describes a HTTP cookie that will be used as the hash key for theConsistent Hash load balancer. If the cookie is not present, it willbe generated.

FieldTypeDescriptionRequired
namestring
Name of the cookie.
Yes
pathstring
Path to set for the cookie.
No
ttlDuration
Lifetime of the cookie.
Yes

LoadBalancerSettings.SimpleLB

Standard load balancing algorithms that require no tuning.

NameDescription
ROUND_ROBIN
Round Robin policy. Default
LEAST_CONN
The least request load balancer uses an O(1) algorithm which selectstwo random healthy hosts and picks the host which has fewer activerequests.
RANDOM
The random load balancer selects a random healthy host. The randomload balancer generally performs better than round robin if no healthchecking policy is configured.
PASSTHROUGH
This option will forward the connection to the original IP addressrequested by the caller without doing any form of loadbalancing. This option must be used with care. It is meant foradvanced use cases. Refer to Original Destination load balancer inEnvoy for further details.

LocalityLoadBalancerSetting

Locality-weighted load balancing allows administrators to control thedistribution of traffic to endpoints based on the localities of where thetraffic originates and where it will terminate. These localities arespecified using arbitrary labels that designate a hierarchy of localities in{region}/{zone}/{sub-zone} form. For additional detail refer toLocality WeightThe following example shows how to setup locality weights mesh-wide.

Given a mesh with workloads and their service deployed to “us-west/zone1/”and “us-west/zone2/”. This example specifies that when traffic accessing aservice originates from workloads in “us-west/zone1/”, 80% of the trafficwill be sent to endpoints in “us-west/zone1/”, i.e the same zone, and theremaining 20% will go to endpoints in “us-west/zone2/”. This setup isintended to favor routing traffic to endpoints in the same locality.A similar setting is specified for traffic originating in “us-west/zone2/”.

  1. distribute:
  2. - from: us-west/zone1/*
  3. to:
  4. "us-west/zone1/*": 80
  5. "us-west/zone2/*": 20
  6. - from: us-west/zone2/*
  7. to:
  8. "us-west/zone1/*": 20
  9. "us-west/zone2/*": 80

If the goal of the operator is not to distribute load across zones andregions but rather to restrict the regionality of failover to meet otheroperational requirements an operator can set a ‘failover’ policy instead ofa ‘distribute’ policy.

The following example sets up a locality failover policy for regions.Assume a service resides in zones within us-east, us-west & eu-westthis example specifies that when endpoints within us-east become unhealthytraffic should failover to endpoints in any zone or sub-zone within eu-westand similarly us-west should failover to us-east.

  1. failover:
  2. - from: us-east
  3. to: eu-west
  4. - from: us-west
  5. to: us-east

Locality load balancing settings.

FieldTypeDescriptionRequired
distributeDistribute[]
Optional: only one of distribute or failover can be set.Explicitly specify loadbalancing weight across different zones and geographical locations.Refer to Locality weighted load balancingIf empty, the locality weight is set according to the endpoints number within it.
No
failoverFailover[]
Optional: only failover or distribute can be set.Explicitly specify the region traffic will land on when endpoints in local region becomes unhealthy.Should be used together with OutlierDetection to detect unhealthy endpoints.Note: if no OutlierDetection specified, this will not take effect.
No

LocalityLoadBalancerSetting.Distribute

Describes how traffic originating in the ‘from’ zone or sub-zone isdistributed over a set of ‘to’ zones. Syntax for specifying a zone is{region}/{zone}/{sub-zone} and terminal wildcards are allowed on anysegment of the specification. Examples: - matches all localitiesus-west/ - all zones and sub-zones within the us-west regionus-west/zone-1/* - all sub-zones within us-west/zone-1

FieldTypeDescriptionRequired
fromstring
Originating locality, ‘/’ separated, e.g. ‘region/zone/sub_zone’.
No
tomap<string, uint32>
Map of upstream localities to traffic distribution weights. The sum ofall weights should be == 100. Any locality not assigned a weight willreceive no traffic.
No

LocalityLoadBalancerSetting.Failover

Specify the traffic failover policy across regions. Since zone and sub-zonefailover is supported by default this only needs to be specified forregions when the operator needs to constrain traffic failover so thatthe default behavior of failing over to any endpoint globally does notapply. This is useful when failing over traffic across regions would notimprove service health or may need to be restricted for other reasonslike regulatory controls.

FieldTypeDescriptionRequired
fromstring
Originating region.
No
tostring
Destination region the traffic will fail over to when endpoints inthe ‘from’ region becomes unhealthy.
No

OutlierDetection

A Circuit breaker implementation that tracks the status of eachindividual host in the upstream service. Applicable to both HTTP andTCP services. For HTTP services, hosts that continually return 5xxerrors for API calls are ejected from the pool for a pre-defined periodof time. For TCP services, connection timeouts or connectionfailures to a given host counts as an error when measuring theconsecutive errors metric. See Envoy’s outlierdetectionfor more details.

The following rule sets a connection pool size of 100 HTTP1 connectionswith no more than 10 req/connection to the “reviews” service. In addition,it sets a limit of 1000 concurrent HTTP2 requests and configures upstreamhosts to be scanned every 5 mins so that any host that fails 7 consecutivetimes with a 502, 503, or 504 error code will be ejected for 15 minutes.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: reviews-cb-policy
  5. spec:
  6. host: reviews.prod.svc.cluster.local
  7. trafficPolicy:
  8. connectionPool:
  9. tcp:
  10. maxConnections: 100
  11. http:
  12. http2MaxRequests: 1000
  13. maxRequestsPerConnection: 10
  14. outlierDetection:
  15. consecutiveErrors: 7
  16. interval: 5m
  17. baseEjectionTime: 15m
FieldTypeDescriptionRequired
consecutiveErrorsint32
Number of errors before a host is ejected from the connectionpool. Defaults to 5. When the upstream host is accessed over HTTP, a502, 503, or 504 return code qualifies as an error. When the upstream hostis accessed over an opaque TCP connection, connect timeouts andconnection error/failure events qualify as an error.
No
intervalDuration
Time interval between ejection sweep analysis. format:1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.
No
baseEjectionTimeDuration
Minimum ejection duration. A host will remain ejected for a periodequal to the product of minimum ejection duration and the number oftimes the host has been ejected. This technique allows the system toautomatically increase the ejection period for unhealthy upstreamservers. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 30s.
No
maxEjectionPercentint32
Maximum % of hosts in the load balancing pool for the upstreamservice that can be ejected. Defaults to 10%.
No
minHealthPercentint32
Outlier detection will be enabled as long as the associated load balancingpool has at least min_health_percent hosts in healthy mode. When thepercentage of healthy hosts in the load balancing pool drops below thisthreshold, outlier detection will be disabled and the proxy will load balanceacross all hosts in the pool (healthy and unhealthy). The threshold can bedisabled by setting it to 0%. The default is 0% as it’s not typicallyapplicable in k8s environments with few pods per service.
No

Subset

A subset of endpoints of a service. Subsets can be used for scenarioslike A/B testing, or routing to a specific version of a service. Referto VirtualService documentation for examples of usingsubsets in these scenarios. In addition, traffic policies defined at theservice-level can be overridden at a subset-level. The following ruleuses a round robin load balancing policy for all traffic going to asubset named testversion that is composed of endpoints (e.g., pods) withlabels (version:v3).

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: bookinfo-ratings
  5. spec:
  6. host: ratings.prod.svc.cluster.local
  7. trafficPolicy:
  8. loadBalancer:
  9. simple: LEAST_CONN
  10. subsets:
  11. - name: testversion
  12. labels:
  13. version: v3
  14. trafficPolicy:
  15. loadBalancer:
  16. simple: ROUND_ROBIN

Note: Policies specified for subsets will not take effect untila route rule explicitly sends traffic to this subset.

One or more labels are typically required to identify the subset destination,however, when the corresponding DestinationRule represents a host thatsupports multiple SNI hosts (e.g., an egress gateway), a subset without labelsmay be meaningful. In this case a traffic policy with TLSSettingscan be used to identify a specific SNI host corresponding to the named subset.

FieldTypeDescriptionRequired
namestring
Name of the subset. The service name and the subset name canbe used for traffic splitting in a route rule.
Yes
labelsmap<string, string>
Labels apply a filter over the endpoints of a service in theservice registry. See route rules for examples of usage.
No
trafficPolicyTrafficPolicy
Traffic policies that apply to this subset. Subsets inherit thetraffic policies specified at the DestinationRule level. Settingsspecified at the subset level will override the corresponding settingsspecified at the DestinationRule level.
No

TLSSettings

SSL/TLS related settings for upstream connections. See Envoy’s TLScontextfor more details. These settings are common to both HTTP and TCP upstreams.

For example, the following rule configures a client to use mutual TLSfor connections to upstream database cluster.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: db-mtls
  5. spec:
  6. host: mydbserver.prod.svc.cluster.local
  7. trafficPolicy:
  8. tls:
  9. mode: MUTUAL
  10. clientCertificate: /etc/certs/myclientcert.pem
  11. privateKey: /etc/certs/client_private_key.pem
  12. caCertificates: /etc/certs/rootcacerts.pem

The following rule configures a client to use TLS when talking to aforeign service whose domain matches *.foo.com.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: tls-foo
  5. spec:
  6. host: "*.foo.com"
  7. trafficPolicy:
  8. tls:
  9. mode: SIMPLE

The following rule configures a client to use Istio mutual TLS when talkingto rating services.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: DestinationRule
  3. metadata:
  4. name: ratings-istio-mtls
  5. spec:
  6. host: ratings.prod.svc.cluster.local
  7. trafficPolicy:
  8. tls:
  9. mode: ISTIO_MUTUAL
FieldTypeDescriptionRequired
modeTLSmode
Indicates whether connections to this port should be securedusing TLS. The value of this field determines how TLS is enforced.
Yes
clientCertificatestring
REQUIRED if mode is MUTUAL. The path to the file holding theclient-side TLS certificate to use.Should be empty if mode is ISTIO_MUTUAL.
No
privateKeystring
REQUIRED if mode is MUTUAL. The path to the file holding theclient’s private key.Should be empty if mode is ISTIO_MUTUAL.
No
caCertificatesstring
OPTIONAL: The path to the file containing certificate authoritycertificates to use in verifying a presented server certificate. Ifomitted, the proxy will not verify the server’s certificate.Should be empty if mode is ISTIO_MUTUAL.
No
subjectAltNamesstring[]
A list of alternate names to verify the subject identity in thecertificate. If specified, the proxy will verify that the servercertificate’s subject alt name matches one of the specified values.If specified, this list overrides the value of subject_alt_namesfrom the ServiceEntry.
No
snistring
SNI string to present to the server during TLS handshake.
No

TLSSettings.TLSmode

TLS connection mode

NameDescription
DISABLE
Do not setup a TLS connection to the upstream endpoint.
SIMPLE
Originate a TLS connection to the upstream endpoint.
MUTUAL
Secure connections to the upstream using mutual TLS by presentingclient certificates for authentication.
ISTIO_MUTUAL
Secure connections to the upstream using mutual TLS by presentingclient certificates for authentication.Compared to Mutual mode, this mode uses certificates generatedautomatically by Istio for mTLS authentication. When this mode isused, all other fields in TLSSettings should be empty.

TrafficPolicy

Traffic policies to apply for a specific destination, across alldestination ports. See DestinationRule for examples.

FieldTypeDescriptionRequired
loadBalancerLoadBalancerSettings
Settings controlling the load balancer algorithms.
No
connectionPoolConnectionPoolSettings
Settings controlling the volume of connections to an upstream service
No
outlierDetectionOutlierDetection
Settings controlling eviction of unhealthy hosts from the load balancing pool
No
tlsTLSSettings
TLS related settings for connections to the upstream service.
No
portLevelSettingsPortTrafficPolicy[]
Traffic policies specific to individual ports. Note that port levelsettings will override the destination-level settings. Trafficsettings specified at the destination-level will not be inherited whenoverridden by port-level settings, i.e. default values will be appliedto fields omitted in port-level traffic policies.
No

TrafficPolicy.PortTrafficPolicy

Traffic policies that apply to specific ports of the service

FieldTypeDescriptionRequired
portPortSelector
Specifies the number of a port on the destination serviceon which this policy is being applied.
No
loadBalancerLoadBalancerSettings
Settings controlling the load balancer algorithms.
No
connectionPoolConnectionPoolSettings
Settings controlling the volume of connections to an upstream service
No
outlierDetectionOutlierDetection
Settings controlling eviction of unhealthy hosts from the load balancing pool
No
tlsTLSSettings
TLS related settings for connections to the upstream service.
No