Destination Rule

The name of a service from the service registry. Service names are looked up from the platform’s service registry (e.g., Kubernetes services, Consul services, etc.) and from the hosts declared by ServiceEntries. Rules defined for services 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 interpret the short name based on the namespace of the rule, not the service. A rule in the “default” namespace containing a host “reviews” will be interpreted as “reviews.default.svc.cluster.local”, irrespective of the actual namespace associated with the reviews service. To avoid potential misconfigurations, it is recommended to always use fully qualified domain names over short names.

Note that the host field applies to both HTTP and TCP services.

Traffic policies to apply (load balancing policy, connection pool sizes, outlier detection).

One or more named sets that represent individual versions of a service. Traffic policies can be overridden at subset level.

A list of namespaces to which this destination rule is exported. The resolution of a destination rule to apply to a service occurs in the context of a hierarchy of namespaces. Exporting a destination rule allows it to be included in the resolution hierarchy for services in other namespaces. This feature provides a mechanism for service owners and mesh administrators to control the visibility of destination rules across namespace boundaries.

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

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

Criteria used to select the specific set of pods/VMs on which this DestinationRule configuration should be applied. If specified, the DestinationRule configuration will be applied only to the workload instances matching the workload selector label in the same namespace. Workload selectors do not apply across namespace boundaries. If omitted, the DestinationRule falls back to its default behavior. For example, if specific sidecars need to have egress TLS settings for services outside of the mesh, instead of every sidecar in the mesh needing to have the configuration (which is the default behaviour), a workload selector can be specified.

Settings controlling the load balancer algorithms.

Settings controlling the volume of connections to an upstream service

Settings controlling eviction of unhealthy hosts from the load balancing pool

TLS related settings for connections to the upstream service.

Traffic policies specific to individual ports. Note that port level settings will override the destination-level settings. Traffic settings specified at the destination-level will not be inherited when overridden by port-level settings, i.e. default values will be applied to fields omitted in port-level traffic policies.

Configuration of tunneling TCP over other transport or application layers for the host configured in the DestinationRule. Tunnel settings can be applied to TCP or TLS routes and can’t be applied to HTTP routes.

The upstream PROXY protocol settings.

Specifies the number of a port on the destination service on which this policy is being applied.

Settings controlling the load balancer algorithms.

Settings controlling the volume of connections to an upstream service

Settings controlling eviction of unhealthy hosts from the load balancing pool

TLS related settings for connections to the upstream service.

Specifies which protocol to use for tunneling the downstream connection. Supported protocols are:

• CONNECT - uses HTTP CONNECT;
• POST - uses HTTP POST.

CONNECT is used by default if not specified.

HTTP version for upstream requests is determined by the service protocol defined for the proxy.

Specifies a host to which the downstream connection is tunneled. Target host must be an FQDN or IP address.

Specifies a port to which the downstream connection is tunneled.

The PROXY protocol version to use. See https://www.haproxy.org/download/2.1/doc/proxy-protocol.txt for details. By default it is V1.

Name of the subset. The service name and the subset name can be used for traffic splitting in a route rule.

Labels apply a filter over the endpoints of a service in the service registry. See route rules for examples of usage.

Traffic policies that apply to this subset. Subsets inherit the traffic policies specified at the DestinationRule level. Settings specified at the subset level will override the corresponding settings specified at the DestinationRule level.

Locality load balancer settings, this will override mesh-wide settings in entirety, meaning no merging would be performed between this object and the object one in MeshConfig

Deprecated: use warmup instead.

Represents the warmup configuration of Service. If set, the newly created endpoint of service remains in warmup mode starting from its creation time for the duration of this window and Istio progressively increases amount of traffic for that endpoint instead of sending proportional amount of traffic. This should be enabled for services that require warm up time to serve full production load with reasonable latency. Please note that this is most effective when few new endpoints come up like scale event in Kubernetes. When all the endpoints are relatively new like new deployment, this is not very effective as all endpoints end up getting same amount of requests. Currently this is only supported for ROUND_ROBIN and LEAST_REQUEST load balancers.

The minimum number of virtual nodes to use for the hash ring. Defaults to 1024. Larger ring sizes result in more granular load distributions. If the number of hosts in the load balancing pool is larger than the ring size, each host will be assigned a single virtual node.

The table size for Maglev hashing. This helps in controlling the disruption when the backend hosts change. Increasing the table size reduces the amount of disruption. The table size must be prime number less than 5000011. If it is not specified, the default is 65537.

Name of the cookie.

Path to set for the cookie.

Lifetime of the cookie. If specified, a cookie with the TTL will be generated if the cookie is not present. If the TTL is present and zero, the generated cookie will be a session cookie.

Duration of warmup mode

Configures the minimum percentage of origin weight If unspecified, defaults to 10

This parameter controls the speed of traffic increase over the warmup duration. Defaults to 1.0, so that endpoints would get linearly increasing amount of traffic. When increasing the value for this parameter, the speed of traffic ramp-up increases non-linearly.

Settings common to both HTTP and TCP upstream connections.

HTTP connection pool settings.

Maximum number of HTTP1 /TCP connections to a destination host. Default 2^32-1.

TCP connection timeout. format: 1h/1m/1s/1ms. MUST be >=1ms. Default is 10s.

If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.

The maximum duration of a connection. The duration is defined as the period since a connection was established. If not set, there is no max duration. When maxConnectionDuration is reached the connection will be closed. Duration must be at least 1ms.

The idle timeout for TCP connections. The idle timeout is defined as the period in which there are no bytes sent or received on either the upstream or downstream connection. If not set, the default idle timeout is 1 hour. If set to 0s, the timeout will be disabled. Idle timeout is not configured per each cluster individually when weighted destinations are used, because idleTimeout is a property of a listener, not a cluster. In that case, idleTimeout specified in a destination rule for the first weighted route is configured in the listener, which means also for all weighted routes.

Maximum number of keepalive probes to send without response before deciding the connection is dead. Default is to use the OS level configuration (unless overridden, Linux defaults to 9.)

The time duration a connection needs to be idle before keep-alive probes start being sent. Default is to use the OS level configuration (unless overridden, Linux defaults to 7200s (ie 2 hours.)

The time duration between keep-alive probes. Default is to use the OS level configuration (unless overridden, Linux defaults to 75s.)

Maximum number of requests that will be queued while waiting for a ready connection pool connection. Default 2^32-1. Refer to https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking under which conditions a new connection is created for HTTP2. Please note that this is applicable to both HTTP/1.1 and HTTP2.

Maximum number of active requests to a destination. Default 2^32-1. Please note that this is applicable to both HTTP/1.1 and HTTP2.

Maximum number of requests per connection to a backend. Setting this parameter to 1 disables keep alive. Default 0, meaning “unlimited”, up to 2^29.

Maximum number of retries that can be outstanding to all hosts in a cluster at a given time. Defaults to 2^32-1.

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. If the connection is an HTTP/2 connection a drain sequence will occur prior to closing the connection. Note that request based timeouts mean that HTTP/2 PINGs will not keep the connection alive. Applies to both HTTP1.1 and HTTP2 connections.

Specify if http1.1 connection should be upgraded to http2 for the associated destination.

If set to true, client protocol will be preserved while initiating connection to backend. Note that when this is set to true, h2UpgradePolicy will be ineffective i.e. the client connections will not be upgraded to http2.

The maximum number of concurrent streams allowed for a peer on one HTTP/2 connection. Defaults to 2^31-1.

Determines whether to distinguish local origin failures from external errors. If set to true consecutiveLocalOriginFailures is taken into account for outlier detection calculations. This should be used when you want to derive the outlier detection status based on the errors seen locally such as failure to connect, timeout while connecting etc. rather than the status code returned by upstream service. This is especially useful when the upstream service explicitly returns a 5xx for some requests and you want to ignore those responses from upstream service while determining the outlier detection status of a host. Defaults to false.

The number of consecutive locally originated failures before ejection occurs. Defaults to 5. Parameter takes effect only when splitExternalLocalOriginErrors is set to true.

Number of gateway errors before a host is ejected from the connection pool. When the upstream host is accessed over HTTP, a 502, 503, or 504 return code qualifies as a gateway error. When the upstream host is accessed over an opaque TCP connection, connect timeouts and connection error/failure events qualify as a gateway error. This feature is disabled by default or when set to the value 0.

Note that consecutiveGatewayErrors and consecutive5xxErrors can be used separately or together. Because the errors counted by consecutiveGatewayErrors are also included in consecutive5xxErrors, if the value of consecutiveGatewayErrors is greater than or equal to the value of consecutive5xxErrors, consecutiveGatewayErrors will have no effect.

Number of 5xx errors before a host is ejected from the connection pool. When the upstream host is accessed over an opaque TCP connection, connect timeouts, connection error/failure and request failure events qualify as a 5xx error. This feature defaults to 5 but can be disabled by setting the value to 0.

Note that consecutiveGatewayErrors and consecutive5xxErrors can be used separately or together. Because the errors counted by consecutiveGatewayErrors are also included in consecutive5xxErrors, if the value of consecutiveGatewayErrors is greater than or equal to the value of consecutive5xxErrors, consecutiveGatewayErrors will have no effect.

Time interval between ejection sweep analysis. format: 1h/1m/1s/1ms. MUST be >=1ms. Default is 10s.

Minimum ejection duration. A host will remain ejected for a period equal to the product of minimum ejection duration and the number of times the host has been ejected. This technique allows the system to automatically increase the ejection period for unhealthy upstream servers. format: 1h/1m/1s/1ms. MUST be >=1ms. Default is 30s.

Maximum % of hosts in the load balancing pool for the upstream service that can be ejected. Defaults to 10%.

Outlier detection will be enabled as long as the associated load balancing pool has at least minHealthPercent hosts in healthy mode. When the percentage of healthy hosts in the load balancing pool drops below this threshold, outlier detection will be disabled and the proxy will load balance across all hosts in the pool (healthy and unhealthy). The threshold can be disabled by setting it to 0%. The default is 0% as it’s not typically applicable in k8s environments with few pods per service.

Indicates whether connections to this port should be secured using TLS. The value of this field determines how TLS is enforced.

REQUIRED if mode is MUTUAL. The path to the file holding the client-side TLS certificate to use. Should be empty if mode is ISTIO_MUTUAL.

REQUIRED if mode is MUTUAL. The path to the file holding the client’s private key. Should be empty if mode is ISTIO_MUTUAL.

OPTIONAL: The path to the file containing certificate authority certificates to use in verifying a presented server certificate. If omitted, the proxy will verify the server’s certificate using the OS CA certificates. Should be empty if mode is ISTIO_MUTUAL.

The name of the secret that holds the TLS certs for the client including the CA certificates. This secret must exist in the namespace of the proxy using the certificates. An Opaque secret should contain the following keys and values: key: <privateKey>, cert: <clientCert>, cacert: <CACertificate>, crl: <certificateRevocationList> Here CACertificate is used to verify the server certificate. For mutual TLS, cacert: <CACertificate> can be provided in the same secret or a separate secret named <secret>-cacert. A TLS secret for client certificates with an additional ca.crt key for CA certificates and ca.crl key for certificate revocation list(CRL) is also supported. Only one of client certificates and CA certificate or credentialName can be specified.

NOTE: This field is applicable at sidecars only if DestinationRule has a workloadSelector specified. Otherwise the field will be applicable only at gateways, and sidecars will continue to use the certificate paths.

A list of alternate names to verify the subject identity in the certificate. If specified, the proxy will verify that the server certificate’s subject alt name matches one of the specified values. If specified, this list overrides the value of subjectAltNames from the ServiceEntry. If unspecified, automatic validation of upstream presented certificate for new upstream connections will be done based on the downstream HTTP host/authority header.

SNI string to present to the server during TLS handshake. If unspecified, SNI will be automatically set based on downstream HTTP host/authority header for SIMPLE and MUTUAL TLS modes.

insecureSkipVerify specifies whether the proxy should skip verifying the CA signature and SAN for the server certificate corresponding to the host. The default value of this field is false.

OPTIONAL: The path to the file containing the certificate revocation list (CRL) to use in verifying a presented server certificate. CRL is a list of certificates that have been revoked by the CA (Certificate Authority) before their scheduled expiration date. If specified, the proxy will verify if the presented certificate is part of the revoked list of certificates. If omitted, the proxy will not verify the certificate against the crl. Note that if credentialName is set, CRL cannot be specified using caCrl, rather it has to be specified inside the credential.

only one of distribute, failover or failoverPriority can be set. Explicitly specify loadbalancing weight across different zones and geographical locations. Refer to Locality weighted load balancing If empty, the locality weight is set according to the endpoints number within it.

only one of distribute, failover or failoverPriority 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.

failoverPriority is an ordered list of labels used to sort endpoints to do priority based load balancing. This is to support traffic failover across different groups of endpoints. Two kinds of labels can be specified:

• Specify only label keys [key1, key2, key3], istio would compare the label values of client with endpoints. Suppose there are total N label keys [key1, key2, key3, ...keyN] specified:

  1. Endpoints matching all N labels with the client proxy have priority P(0) i.e. the highest priority.
  2. Endpoints matching the first N-1 labels with the client proxy have priority P(1) i.e. second highest priority.
  3. By extension of this logic, endpoints matching only the first label with the client proxy has priority P(N-1) i.e. second lowest priority.
  4. All the other endpoints have priority P(N) i.e. lowest priority.

• Specify labels with key and value [key1=value1, key2=value2, key3=value3], istio would compare the labels with endpoints. Suppose there are total N labels [key1=value1, key2=value2, key3=value3, ...keyN=valueN] specified:

  1. Endpoints matching all N labels have priority P(0) i.e. the highest priority.
  2. Endpoints matching the first N-1 labels have priority P(1) i.e. second highest priority.
  3. By extension of this logic, endpoints matching only the first label has priority P(N-1) i.e. second lowest priority.
  4. All the other endpoints have priority P(N) i.e. lowest priority.

Note: For a label to be considered for match, the previous labels must match, i.e. nth label would be considered matched only if first n-1 labels match.

It can be any label specified on both client and server workloads. The following labels which have special semantic meaning are also supported:

• topology.istio.io/network is used to match the network metadata of an endpoint, which can be specified by pod/namespace label topology.istio.io/network, sidecar env ISTIO_META_NETWORK or MeshNetworks.
• topology.istio.io/cluster is used to match the clusterID of an endpoint, which can be specified by pod label topology.istio.io/cluster or pod env ISTIO_META_CLUSTER_ID.
• topology.kubernetes.io/region is used to match the region metadata of an endpoint, which maps to Kubernetes node label topology.kubernetes.io/region or the deprecated label failure-domain.beta.kubernetes.io/region.
• topology.kubernetes.io/zone is used to match the zone metadata of an endpoint, which maps to Kubernetes node label topology.kubernetes.io/zone or the deprecated label failure-domain.beta.kubernetes.io/zone.
• topology.istio.io/subzone is used to match the subzone metadata of an endpoint, which maps to Istio node label topology.istio.io/subzone.
• kubernetes.io/hostname is used to match the current node of an endpoint, which maps to Kubernetes node label kubernetes.io/hostname.

The below topology config indicates the following priority levels:

failoverPriority:
- "topology.istio.io/network"
- "topology.kubernetes.io/region"
- "topology.kubernetes.io/zone"
- "topology.istio.io/subzone"

1. endpoints match same [network, region, zone, subzone] label with the client proxy have the highest priority.
2. endpoints have same [network, region, zone] label but different [subzone] label with the client proxy have the second highest priority.
3. endpoints have same [network, region] label but different [zone] label with the client proxy have the third highest priority.
4. endpoints have same [network] but different [region] labels with the client proxy have the fourth highest priority.
5. all the other endpoints have the same lowest priority.

Suppose a service associated endpoints reside in multi clusters, the below example represents:

1. endpoints in clusterA and has version=v1 label have P(0) priority.
2. endpoints not in clusterA but has version=v1 label have P(1) priority.
3. all the other endpoints have P(2) priority.

failoverPriority:
- "version=v1"
- "topology.istio.io/cluster=clusterA"

only one of distribute, failover or failoverPriority can be set. And it should be used together with OutlierDetection to detect unhealthy endpoints, otherwise has no effect.

Enable locality load balancing. This is DestinationRule-level and will override mesh-wide settings in entirety. e.g. true means that turn on locality load balancing for this DestinationRule no matter what mesh-wide settings is.

Originating locality, ‘/’ separated, e.g. ‘region/zone/sub_zone’.

Map of upstream localities to traffic distribution weights. The sum of all weights should be 100. Any locality not present will receive no traffic.

Originating region.

Destination region the traffic will fail over to when endpoints in the ‘from’ region becomes unhealthy.

The uint32 value.