Destination Rule

    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.   name: bookinfo-ratings-port
    4. spec:
    5.   host: ratings.prod.svc.cluster.local
    6.   trafficPolicy: # Apply to all ports
    7.     portLevelSettings:
    8.     - port:
    9.         number: 80
    10.       loadBalancer:
    11.         simple: LEAST_CONN
    12.     - port:
    13.         number: 9080
    14.       loadBalancer:
    15.         simple: ROUND_ROBIN

    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

    ConnectionPoolSettings.HTTPSettings

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

    FieldTypeDescriptionRequired
    http1MaxPendingRequestsint32Maximum number of pending HTTP requests to a destination. Default 2^32-1.No
    http2MaxRequestsint32Maximum number of requests to a backend. Default 2^32-1.No
    maxRequestsPerConnectionint32Maximum number of requests per connection to a backend. Setting thisparameter to 1 disables keep alive. Default 0, meaning “unlimited”,up to 2^29.No
    maxRetriesint32Maximum number of retries that can be outstanding to all hosts in acluster at a given time. Defaults to 2^32-1.No
    idleTimeoutDurationThe 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, there is no idle timeout. 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
    h2UpgradePolicySpecify 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
    DEFAULTUse the global default.
    DO_NOT_UPGRADEDo not upgrade the connection to http2.This opt-out option overrides the default.
    UPGRADEUpgrade the connection to http2.This opt-in option overrides the default.

    ConnectionPoolSettings.TCPSettings

    Settings common to both HTTP and TCP upstream connections.

    FieldTypeDescriptionRequired
    maxConnectionsint32Maximum number of HTTP1 /TCP connections to a destination host. Default 2^32-1.No
    connectTimeoutDurationTCP connection timeout.No
    tcpKeepaliveIf set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.No

    ConnectionPoolSettings.TCPSettings.TcpKeepalive

    FieldTypeDescriptionRequired
    probesuint32Maximum 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
    timeThe 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
    intervalDurationThe time duration between keep-alive probes.Default is to use the OS level configuration(unless overridden, Linux defaults to 75s.)No

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

    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
    simpleYes
    consistentHashConsistentHashLB (oneof)Yes

    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
    minimumRingSizeuint64The 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
    namestringName of the cookie.Yes
    pathstringPath to set for the cookie.No
    ttlDurationLifetime of the cookie.Yes

    LoadBalancerSettings.SimpleLB

    Standard load balancing algorithms that require no tuning.

    NameDescription
    ROUND_ROBINRound Robin policy. Default
    LEAST_CONNThe least request load balancer uses an O(1) algorithm which selectstwo random healthy hosts and picks the host which has fewer activerequests.
    RANDOMThe random load balancer selects a random healthy host. The randomload balancer generally performs better than round robin if no healthchecking policy is configured.
    PASSTHROUGHThis 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.

    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.

    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. kind: DestinationRule
    2. metadata:
    3.   name: bookinfo-ratings
    4. spec:
    5.   host: ratings.prod.svc.cluster.local
    6.   trafficPolicy:
    7.     loadBalancer:
    8.       simple: LEAST_CONN
    9.   subsets:
    10.   - name: testversion
    11.     labels:
    12.       version: v3
    14.       loadBalancer:
    15.         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 can be used to identify a specific SNI host corresponding to the named subset.

    FieldTypeDescriptionRequired
    namestringName 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
    trafficPolicyTrafficPolicyTraffic 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.

    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.       mode: ISTIO_MUTUAL
    FieldTypeDescriptionRequired
    modeIndicates whether connections to this port should be securedusing TLS. The value of this field determines how TLS is enforced.Yes
    clientCertificatestringREQUIRED 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
    privateKeystringREQUIRED if mode is MUTUAL. The path to the file holding theclient’s private key.Should be empty if mode is ISTIO_MUTUAL.No
    caCertificatesstringOPTIONAL: 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
    snistringSNI string to present to the server during TLS handshake.No

    TLSSettings.TLSmode

    TLS connection mode

    NameDescription
    DISABLEDo not setup a TLS connection to the upstream endpoint.
    SIMPLEOriginate a TLS connection to the upstream endpoint.
    MUTUALSecure connections to the upstream using mutual TLS by presentingclient certificates for authentication.
    ISTIO_MUTUALSecure 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

    FieldTypeDescriptionRequired
    loadBalancerLoadBalancerSettingsSettings controlling the load balancer algorithms.No
    connectionPoolSettings controlling the volume of connections to an upstream serviceNo
    outlierDetectionOutlierDetectionSettings controlling eviction of unhealthy hosts from the load balancing poolNo
    tlsTLS 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

    Traffic policies that apply to specific ports of the service