istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
istio.io/content/en/docs/reference/config/networking/destination-rule/index.html

1262 lines
34 KiB
HTML
Raw Blame History

---
WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE 'https://github.com/istio/api' REPO
source_repo: https://github.com/istio/api
title: Destination Rule
description: Configuration affecting load balancing, outlier detection, etc.
location: https://istio.io/docs/reference/config/networking/destination-rule.html
layout: protoc-gen-docs
generator: protoc-gen-docs
aliases: [/docs/reference/config/networking/v1alpha3/destination-rule.html]
number_of_entries: 16
---
<p><code>DestinationRule</code> defines policies that apply to traffic intended for a
service after routing has occurred. These rules specify configuration
for load balancing, connection pool size from the sidecar, and outlier
detection settings to detect and evict unhealthy hosts from the load
balancing pool. For example, a simple load balancing policy for the
ratings service would look as follows:</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
loadBalancer:
simple: LEAST_CONN
</code></pre>
<p>Version specific policies can be specified by defining a named
<code>subset</code> and overriding the settings specified at the service level. The
following rule uses a round robin load balancing policy for all traffic
going to a subset named testversion that is composed of endpoints (e.g.,
pods) with labels (version:v3).</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
loadBalancer:
simple: LEAST_CONN
subsets:
- name: testversion
labels:
version: v3
trafficPolicy:
loadBalancer:
simple: ROUND_ROBIN
</code></pre>
<p><strong>Note:</strong> Policies specified for subsets will not take effect until
a route rule explicitly sends traffic to this subset.</p>
<p>Traffic policies can be customized to specific ports as well. The
following rule uses the least connection load balancing policy for all
traffic to port 80, while uses a round robin load balancing setting for
traffic to the port 9080.</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings-port
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy: # Apply to all ports
portLevelSettings:
- port:
number: 80
loadBalancer:
simple: LEAST_CONN
- port:
number: 9080
loadBalancer:
simple: ROUND_ROBIN
</code></pre>
<h2 id="ConnectionPoolSettings">ConnectionPoolSettings</h2>
<section>
<p>Connection pool settings for an upstream host. The settings apply to
each individual host in the upstream service. See Envoy&rsquo;s <a href="https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking">circuit
breaker</a>
for more details. Connection pool settings can be applied at the TCP
level as well as at HTTP level.</p>
<p>For example, the following rule sets a limit of 100 connections to redis
service called myredissrv with a connect timeout of 30ms</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-redis
spec:
host: myredissrv.prod.svc.cluster.local
trafficPolicy:
connectionPool:
tcp:
maxConnections: 100
connectTimeout: 30ms
tcpKeepalive:
time: 7200s
interval: 75s
</code></pre>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="ConnectionPoolSettings-tcp">
<td><code>tcp</code></td>
<td><code><a href="#ConnectionPoolSettings-TCPSettings">TCPSettings</a></code></td>
<td>
<p>Settings common to both HTTP and TCP upstream connections.</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-http">
<td><code>http</code></td>
<td><code><a href="#ConnectionPoolSettings-HTTPSettings">HTTPSettings</a></code></td>
<td>
<p>HTTP connection pool settings.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ConnectionPoolSettings-HTTPSettings">ConnectionPoolSettings.HTTPSettings</h2>
<section>
<p>Settings applicable to HTTP1.1/HTTP2/GRPC connections.</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="ConnectionPoolSettings-HTTPSettings-http1_max_pending_requests">
<td><code>http1MaxPendingRequests</code></td>
<td><code>int32</code></td>
<td>
<p>Maximum number of pending HTTP requests to a destination. Default 1024.</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-HTTPSettings-http2_max_requests">
<td><code>http2MaxRequests</code></td>
<td><code>int32</code></td>
<td>
<p>Maximum number of requests to a backend. Default 1024.</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-HTTPSettings-max_requests_per_connection">
<td><code>maxRequestsPerConnection</code></td>
<td><code>int32</code></td>
<td>
<p>Maximum number of requests per connection to a backend. Setting this
parameter to 1 disables keep alive. Default 0, meaning &ldquo;unlimited&rdquo;,
up to 2^29.</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-HTTPSettings-max_retries">
<td><code>maxRetries</code></td>
<td><code>int32</code></td>
<td>
<p>Maximum number of retries that can be outstanding to all hosts in a
cluster at a given time. Defaults to 1024.</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-HTTPSettings-idle_timeout">
<td><code>idleTimeout</code></td>
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></code></td>
<td>
<p>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, 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.</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-HTTPSettings-h2_upgrade_policy">
<td><code>h2UpgradePolicy</code></td>
<td><code><a href="#ConnectionPoolSettings-HTTPSettings-H2UpgradePolicy">H2UpgradePolicy</a></code></td>
<td>
<p>Specify if http1.1 connection should be upgraded to http2 for the associated destination.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ConnectionPoolSettings-HTTPSettings-H2UpgradePolicy">ConnectionPoolSettings.HTTPSettings.H2UpgradePolicy</h2>
<section>
<p>Policy for upgrading http1.1 connections to http2.</p>
<table class="enum-values">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="ConnectionPoolSettings-HTTPSettings-H2UpgradePolicy-DEFAULT">
<td><code>DEFAULT</code></td>
<td>
<p>Use the global default.</p>
</td>
</tr>
<tr id="ConnectionPoolSettings-HTTPSettings-H2UpgradePolicy-DO_NOT_UPGRADE">
<td><code>DO_NOT_UPGRADE</code></td>
<td>
<p>Do not upgrade the connection to http2.
This opt-out option overrides the default.</p>
</td>
</tr>
<tr id="ConnectionPoolSettings-HTTPSettings-H2UpgradePolicy-UPGRADE">
<td><code>UPGRADE</code></td>
<td>
<p>Upgrade the connection to http2.
This opt-in option overrides the default.</p>
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ConnectionPoolSettings-TCPSettings">ConnectionPoolSettings.TCPSettings</h2>
<section>
<p>Settings common to both HTTP and TCP upstream connections.</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="ConnectionPoolSettings-TCPSettings-max_connections">
<td><code>maxConnections</code></td>
<td><code>int32</code></td>
<td>
<p>Maximum number of HTTP1 /TCP connections to a destination host. Default 1024.</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-TCPSettings-connect_timeout">
<td><code>connectTimeout</code></td>
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></code></td>
<td>
<p>TCP connection timeout.</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-TCPSettings-tcp_keepalive">
<td><code>tcpKeepalive</code></td>
<td><code><a href="#ConnectionPoolSettings-TCPSettings-TcpKeepalive">TcpKeepalive</a></code></td>
<td>
<p>If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ConnectionPoolSettings-TCPSettings-TcpKeepalive">ConnectionPoolSettings.TCPSettings.TcpKeepalive</h2>
<section>
<p>TCP keepalive.</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="ConnectionPoolSettings-TCPSettings-TcpKeepalive-probes">
<td><code>probes</code></td>
<td><code>uint32</code></td>
<td>
<p>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.)</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-TCPSettings-TcpKeepalive-time">
<td><code>time</code></td>
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></code></td>
<td>
<p>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.)</p>
</td>
<td>
No
</td>
</tr>
<tr id="ConnectionPoolSettings-TCPSettings-TcpKeepalive-interval">
<td><code>interval</code></td>
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></code></td>
<td>
<p>The time duration between keep-alive probes.
Default is to use the OS level configuration
(unless overridden, Linux defaults to 75s.)</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="DestinationRule">DestinationRule</h2>
<section>
<p>DestinationRule defines policies that apply to traffic intended for a service
after routing has occurred.</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="DestinationRule-host">
<td><code>host</code></td>
<td><code>string</code></td>
<td>
<p>The name of a service from the service registry. Service
names are looked up from the platform&rsquo;s service registry (e.g.,
Kubernetes services, Consul services, etc.) and from the hosts
declared by <a href="/docs/reference/config/networking/service-entry/#ServiceEntry">ServiceEntries</a>. Rules defined for
services that do not exist in the service registry will be ignored.</p>
<p><em>Note for Kubernetes users</em>: When short names are used (e.g. &ldquo;reviews&rdquo;
instead of &ldquo;reviews.default.svc.cluster.local&rdquo;), Istio will interpret
the short name based on the namespace of the rule, not the service. A
rule in the &ldquo;default&rdquo; namespace containing a host &ldquo;reviews&rdquo; will be
interpreted as &ldquo;reviews.default.svc.cluster.local&rdquo;, irrespective of
the actual namespace associated with the reviews service. <em>To avoid
potential misconfigurations, it is recommended to always use fully
qualified domain names over short names.</em></p>
<p>Note that the host field applies to both HTTP and TCP services.</p>
</td>
<td>
Yes
</td>
</tr>
<tr id="DestinationRule-traffic_policy">
<td><code>trafficPolicy</code></td>
<td><code><a href="#TrafficPolicy">TrafficPolicy</a></code></td>
<td>
<p>Traffic policies to apply (load balancing policy, connection pool
sizes, outlier detection).</p>
</td>
<td>
No
</td>
</tr>
<tr id="DestinationRule-subsets">
<td><code>subsets</code></td>
<td><code><a href="#Subset">Subset[]</a></code></td>
<td>
<p>One or more named sets that represent individual versions of a
service. Traffic policies can be overridden at subset level.</p>
</td>
<td>
No
</td>
</tr>
<tr id="DestinationRule-export_to">
<td><code>exportTo</code></td>
<td><code>string[]</code></td>
<td>
<p>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.</p>
<p>If no namespaces are specified then the destination rule is exported to all
namespaces by default.</p>
<p>The value &ldquo;.&rdquo; is reserved and defines an export to the same namespace that
the destination rule is declared in. Similarly, the value &ldquo;*&rdquo; is reserved and
defines an export to all namespaces.</p>
<p>NOTE: in the current release, the <code>exportTo</code> value is restricted to
&ldquo;.&rdquo; or &ldquo;*&rdquo; (i.e., the current namespace or all namespaces).</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="LoadBalancerSettings">LoadBalancerSettings</h2>
<section>
<p>Load balancing policies to apply for a specific destination. See Envoy&rsquo;s
load balancing
<a href="https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancing">documentation</a>
for more details.</p>
<p>For example, the following rule uses a round robin load balancing policy
for all traffic going to the ratings service.</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
loadBalancer:
simple: ROUND_ROBIN
</code></pre>
<p>The following example sets up sticky sessions for the ratings service
hashing-based load balancer for the same ratings service using the
the User cookie as the hash key.</p>
<pre><code class="language-yaml"> apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
loadBalancer:
consistentHash:
httpCookie:
name: user
ttl: 0s
</code></pre>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="LoadBalancerSettings-simple" class="oneof oneof-start">
<td><code>simple</code></td>
<td><code><a href="#LoadBalancerSettings-SimpleLB">SimpleLB (oneof)</a></code></td>
<td>
</td>
<td>
Yes
</td>
</tr>
<tr id="LoadBalancerSettings-consistent_hash" class="oneof">
<td><code>consistentHash</code></td>
<td><code><a href="#LoadBalancerSettings-ConsistentHashLB">ConsistentHashLB (oneof)</a></code></td>
<td>
</td>
<td>
Yes
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="LoadBalancerSettings-ConsistentHashLB">LoadBalancerSettings.ConsistentHashLB</h2>
<section>
<p>Consistent Hash-based load balancing can be used to provide soft
session affinity based on HTTP headers, cookies or other
properties. This load balancing policy is applicable only for HTTP
connections. The affinity to a particular destination host will be
lost when one or more hosts are added/removed from the destination
service.</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="LoadBalancerSettings-ConsistentHashLB-http_header_name" class="oneof oneof-start">
<td><code>httpHeaderName</code></td>
<td><code>string (oneof)</code></td>
<td>
<p>Hash based on a specific HTTP header.</p>
</td>
<td>
Yes
</td>
</tr>
<tr id="LoadBalancerSettings-ConsistentHashLB-http_cookie" class="oneof">
<td><code>httpCookie</code></td>
<td><code><a href="#LoadBalancerSettings-ConsistentHashLB-HTTPCookie">HTTPCookie (oneof)</a></code></td>
<td>
<p>Hash based on HTTP cookie.</p>
</td>
<td>
Yes
</td>
</tr>
<tr id="LoadBalancerSettings-ConsistentHashLB-use_source_ip" class="oneof">
<td><code>useSourceIp</code></td>
<td><code>bool (oneof)</code></td>
<td>
<p>Hash based on the source IP address.</p>
</td>
<td>
Yes
</td>
</tr>
<tr id="LoadBalancerSettings-ConsistentHashLB-minimum_ring_size">
<td><code>minimumRingSize</code></td>
<td><code>uint64</code></td>
<td>
<p>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.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="LoadBalancerSettings-ConsistentHashLB-HTTPCookie">LoadBalancerSettings.ConsistentHashLB.HTTPCookie</h2>
<section>
<p>Describes a HTTP cookie that will be used as the hash key for the
Consistent Hash load balancer. If the cookie is not present, it will
be generated.</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="LoadBalancerSettings-ConsistentHashLB-HTTPCookie-name">
<td><code>name</code></td>
<td><code>string</code></td>
<td>
<p>Name of the cookie.</p>
</td>
<td>
Yes
</td>
</tr>
<tr id="LoadBalancerSettings-ConsistentHashLB-HTTPCookie-path">
<td><code>path</code></td>
<td><code>string</code></td>
<td>
<p>Path to set for the cookie.</p>
</td>
<td>
No
</td>
</tr>
<tr id="LoadBalancerSettings-ConsistentHashLB-HTTPCookie-ttl">
<td><code>ttl</code></td>
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></code></td>
<td>
<p>Lifetime of the cookie.</p>
</td>
<td>
Yes
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="LoadBalancerSettings-SimpleLB">LoadBalancerSettings.SimpleLB</h2>
<section>
<p>Standard load balancing algorithms that require no tuning.</p>
<table class="enum-values">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="LoadBalancerSettings-SimpleLB-ROUND_ROBIN">
<td><code>ROUND_ROBIN</code></td>
<td>
<p>Round Robin policy. Default</p>
</td>
</tr>
<tr id="LoadBalancerSettings-SimpleLB-LEAST_CONN">
<td><code>LEAST_CONN</code></td>
<td>
<p>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.</p>
</td>
</tr>
<tr id="LoadBalancerSettings-SimpleLB-RANDOM">
<td><code>RANDOM</code></td>
<td>
<p>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.</p>
</td>
</tr>
<tr id="LoadBalancerSettings-SimpleLB-PASSTHROUGH">
<td><code>PASSTHROUGH</code></td>
<td>
<p>This option will forward the connection to the original IP address
requested by the caller without doing any form of load
balancing. This option must be used with care. It is meant for
advanced use cases. Refer to Original Destination load balancer in
Envoy for further details.</p>
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="OutlierDetection">OutlierDetection</h2>
<section>
<p>A Circuit breaker implementation that tracks the status of each
individual host in the upstream service. Applicable to both HTTP and
TCP services. For HTTP services, hosts that continually return 5xx
errors for API calls are ejected from the pool for a pre-defined period
of time. For TCP services, connection timeouts or connection
failures to a given host counts as an error when measuring the
consecutive errors metric. See Envoy&rsquo;s <a href="https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/outlier">outlier
detection</a>
for more details.</p>
<p>The following rule sets a connection pool size of 100 HTTP1 connections
with no more than 10 req/connection to the &ldquo;reviews&rdquo; service. In addition,
it sets a limit of 1000 concurrent HTTP2 requests and configures upstream
hosts to be scanned every 5 mins so that any host that fails 7 consecutive
times with a 502, 503, or 504 error code will be ejected for 15 minutes.</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: reviews-cb-policy
spec:
host: reviews.prod.svc.cluster.local
trafficPolicy:
connectionPool:
tcp:
maxConnections: 100
http:
http2MaxRequests: 1000
maxRequestsPerConnection: 10
outlierDetection:
consecutiveErrors: 7
interval: 5m
baseEjectionTime: 15m
</code></pre>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="OutlierDetection-consecutive_errors">
<td><code>consecutiveErrors</code></td>
<td><code>int32</code></td>
<td>
<p>Number of errors before a host is ejected from the connection
pool. Defaults to 5. When the upstream host is accessed over HTTP, a
502, 503, or 504 return code qualifies as an error. When the upstream host
is accessed over an opaque TCP connection, connect timeouts and
connection error/failure events qualify as an error.</p>
</td>
<td>
No
</td>
</tr>
<tr id="OutlierDetection-interval">
<td><code>interval</code></td>
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></code></td>
<td>
<p>Time interval between ejection sweep analysis. format:
1h/1m/1s/1ms. MUST BE &gt;=1ms. Default is 10s.</p>
</td>
<td>
No
</td>
</tr>
<tr id="OutlierDetection-base_ejection_time">
<td><code>baseEjectionTime</code></td>
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></code></td>
<td>
<p>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 &gt;=1ms. Default is 30s.</p>
</td>
<td>
No
</td>
</tr>
<tr id="OutlierDetection-max_ejection_percent">
<td><code>maxEjectionPercent</code></td>
<td><code>int32</code></td>
<td>
<p>Maximum % of hosts in the load balancing pool for the upstream
service that can be ejected. Defaults to 10%.</p>
</td>
<td>
No
</td>
</tr>
<tr id="OutlierDetection-min_health_percent">
<td><code>minHealthPercent</code></td>
<td><code>int32</code></td>
<td>
<p>Outlier detection will be enabled as long as the associated load balancing
pool has at least min<em>health</em>percent 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&rsquo;s not typically
applicable in k8s environments with few pods per service.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="Subset">Subset</h2>
<section>
<p>A subset of endpoints of a service. Subsets can be used for scenarios
like A/B testing, or routing to a specific version of a service. Refer
to <a href="/docs/reference/config/networking/virtual-service/#VirtualService">VirtualService</a> documentation for examples of using
subsets in these scenarios. In addition, traffic policies defined at the
service-level can be overridden at a subset-level. The following rule
uses a round robin load balancing policy for all traffic going to a
subset named testversion that is composed of endpoints (e.g., pods) with
labels (version:v3).</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
loadBalancer:
simple: LEAST_CONN
subsets:
- name: testversion
labels:
version: v3
trafficPolicy:
loadBalancer:
simple: ROUND_ROBIN
</code></pre>
<p><strong>Note:</strong> Policies specified for subsets will not take effect until
a route rule explicitly sends traffic to this subset.</p>
<p>One or more labels are typically required to identify the subset destination,
however, when the corresponding DestinationRule represents a host that
supports multiple SNI hosts (e.g., an egress gateway), a subset without labels
may be meaningful. In this case a traffic policy with <a href="#TLSSettings">TLSSettings</a>
can be used to identify a specific SNI host corresponding to the named subset.</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="Subset-name">
<td><code>name</code></td>
<td><code>string</code></td>
<td>
<p>Name of the subset. The service name and the subset name can
be used for traffic splitting in a route rule.</p>
</td>
<td>
Yes
</td>
</tr>
<tr id="Subset-labels">
<td><code>labels</code></td>
<td><code>map&lt;string,&nbsp;string&gt;</code></td>
<td>
<p>Labels apply a filter over the endpoints of a service in the
service registry. See route rules for examples of usage.</p>
</td>
<td>
No
</td>
</tr>
<tr id="Subset-traffic_policy">
<td><code>trafficPolicy</code></td>
<td><code><a href="#TrafficPolicy">TrafficPolicy</a></code></td>
<td>
<p>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.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="TLSSettings">TLSSettings</h2>
<section>
<p>SSL/TLS related settings for upstream connections. See Envoy&rsquo;s <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/auth/cert.proto.html">TLS
context</a>
for more details. These settings are common to both HTTP and TCP upstreams.</p>
<p>For example, the following rule configures a client to use mutual TLS
for connections to upstream database cluster.</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: db-mtls
spec:
host: mydbserver.prod.svc.cluster.local
trafficPolicy:
tls:
mode: MUTUAL
clientCertificate: /etc/certs/myclientcert.pem
privateKey: /etc/certs/client_private_key.pem
caCertificates: /etc/certs/rootcacerts.pem
</code></pre>
<p>The following rule configures a client to use TLS when talking to a
foreign service whose domain matches *.foo.com.</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: tls-foo
spec:
host: &quot;*.foo.com&quot;
trafficPolicy:
tls:
mode: SIMPLE
</code></pre>
<p>The following rule configures a client to use Istio mutual TLS when talking
to rating services.</p>
<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: ratings-istio-mtls
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
tls:
mode: ISTIO_MUTUAL
</code></pre>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="TLSSettings-mode">
<td><code>mode</code></td>
<td><code><a href="#TLSSettings-TLSmode">TLSmode</a></code></td>
<td>
<p>Indicates whether connections to this port should be secured
using TLS. The value of this field determines how TLS is enforced.</p>
</td>
<td>
Yes
</td>
</tr>
<tr id="TLSSettings-client_certificate">
<td><code>clientCertificate</code></td>
<td><code>string</code></td>
<td>
<p>REQUIRED if mode is <code>MUTUAL</code>. The path to the file holding the
client-side TLS certificate to use.
Should be empty if mode is <code>ISTIO_MUTUAL</code>.</p>
</td>
<td>
No
</td>
</tr>
<tr id="TLSSettings-private_key">
<td><code>privateKey</code></td>
<td><code>string</code></td>
<td>
<p>REQUIRED if mode is <code>MUTUAL</code>. The path to the file holding the
client&rsquo;s private key.
Should be empty if mode is <code>ISTIO_MUTUAL</code>.</p>
</td>
<td>
No
</td>
</tr>
<tr id="TLSSettings-ca_certificates">
<td><code>caCertificates</code></td>
<td><code>string</code></td>
<td>
<p>OPTIONAL: The path to the file containing certificate authority
certificates to use in verifying a presented server certificate. If
omitted, the proxy will not verify the server&rsquo;s certificate.
Should be empty if mode is <code>ISTIO_MUTUAL</code>.</p>
</td>
<td>
No
</td>
</tr>
<tr id="TLSSettings-subject_alt_names">
<td><code>subjectAltNames</code></td>
<td><code>string[]</code></td>
<td>
<p>A list of alternate names to verify the subject identity in the
certificate. If specified, the proxy will verify that the server
certificate&rsquo;s subject alt name matches one of the specified values.
If specified, this list overrides the value of subject<em>alt</em>names
from the ServiceEntry.</p>
</td>
<td>
No
</td>
</tr>
<tr id="TLSSettings-sni">
<td><code>sni</code></td>
<td><code>string</code></td>
<td>
<p>SNI string to present to the server during TLS handshake.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="TLSSettings-TLSmode">TLSSettings.TLSmode</h2>
<section>
<p>TLS connection mode</p>
<table class="enum-values">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="TLSSettings-TLSmode-DISABLE">
<td><code>DISABLE</code></td>
<td>
<p>Do not setup a TLS connection to the upstream endpoint.</p>
</td>
</tr>
<tr id="TLSSettings-TLSmode-SIMPLE">
<td><code>SIMPLE</code></td>
<td>
<p>Originate a TLS connection to the upstream endpoint.</p>
</td>
</tr>
<tr id="TLSSettings-TLSmode-MUTUAL">
<td><code>MUTUAL</code></td>
<td>
<p>Secure connections to the upstream using mutual TLS by presenting
client certificates for authentication.</p>
</td>
</tr>
<tr id="TLSSettings-TLSmode-ISTIO_MUTUAL">
<td><code>ISTIO_MUTUAL</code></td>
<td>
<p>Secure connections to the upstream using mutual TLS by presenting
client certificates for authentication.
Compared to Mutual mode, this mode uses certificates generated
automatically by Istio for mTLS authentication. When this mode is
used, all other fields in <code>TLSSettings</code> should be empty.</p>
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="TrafficPolicy">TrafficPolicy</h2>
<section>
<p>Traffic policies to apply for a specific destination, across all
destination ports. See DestinationRule for examples.</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="TrafficPolicy-load_balancer">
<td><code>loadBalancer</code></td>
<td><code><a href="#LoadBalancerSettings">LoadBalancerSettings</a></code></td>
<td>
<p>Settings controlling the load balancer algorithms.</p>
</td>
<td>
No
</td>
</tr>
<tr id="TrafficPolicy-connection_pool">
<td><code>connectionPool</code></td>
<td><code><a href="#ConnectionPoolSettings">ConnectionPoolSettings</a></code></td>
<td>
<p>Settings controlling the volume of connections to an upstream service</p>
</td>
<td>
No
</td>
</tr>
<tr id="TrafficPolicy-outlier_detection">
<td><code>outlierDetection</code></td>
<td><code><a href="#OutlierDetection">OutlierDetection</a></code></td>
<td>
<p>Settings controlling eviction of unhealthy hosts from the load balancing pool</p>
</td>
<td>
No
</td>
</tr>
<tr id="TrafficPolicy-tls">
<td><code>tls</code></td>
<td><code><a href="#TLSSettings">TLSSettings</a></code></td>
<td>
<p>TLS related settings for connections to the upstream service.</p>
</td>
<td>
No
</td>
</tr>
<tr id="TrafficPolicy-port_level_settings">
<td><code>portLevelSettings</code></td>
<td><code><a href="#TrafficPolicy-PortTrafficPolicy">PortTrafficPolicy[]</a></code></td>
<td>
<p>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.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
<h2 id="TrafficPolicy-PortTrafficPolicy">TrafficPolicy.PortTrafficPolicy</h2>
<section>
<p>Traffic policies that apply to specific ports of the service</p>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr id="TrafficPolicy-PortTrafficPolicy-port">
<td><code>port</code></td>
<td><code><a href="/docs/reference/config/networking/virtual-service.html#PortSelector">PortSelector</a></code></td>
<td>
<p>Specifies the number of a port on the destination service
on which this policy is being applied.</p>
</td>
<td>
No
</td>
</tr>
<tr id="TrafficPolicy-PortTrafficPolicy-load_balancer">
<td><code>loadBalancer</code></td>
<td><code><a href="#LoadBalancerSettings">LoadBalancerSettings</a></code></td>
<td>
<p>Settings controlling the load balancer algorithms.</p>
</td>
<td>
No
</td>
</tr>
<tr id="TrafficPolicy-PortTrafficPolicy-connection_pool">
<td><code>connectionPool</code></td>
<td><code><a href="#ConnectionPoolSettings">ConnectionPoolSettings</a></code></td>
<td>
<p>Settings controlling the volume of connections to an upstream service</p>
</td>
<td>
No
</td>
</tr>
<tr id="TrafficPolicy-PortTrafficPolicy-outlier_detection">
<td><code>outlierDetection</code></td>
<td><code><a href="#OutlierDetection">OutlierDetection</a></code></td>
<td>
<p>Settings controlling eviction of unhealthy hosts from the load balancing pool</p>
</td>
<td>
No
</td>
</tr>
<tr id="TrafficPolicy-PortTrafficPolicy-tls">
<td><code>tls</code></td>
<td><code><a href="#TLSSettings">TLSSettings</a></code></td>
<td>
<p>TLS related settings for connections to the upstream service.</p>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</section>
Reference in New Issue View Git Blame Copy Permalink