destination_rule.proto
Package: istio.networking.v1alpha3
Types:
- DestinationRule Top-Level Resource
- TrafficPolicy
- PortTrafficPolicy
- Subset
- LoadBalancerSettings
- ConsistentHashLB
- HTTPCookie
- LocalityWeightSetting
- SimpleLB
- ConnectionPoolSettings
- TCPSettings
- TcpKeepalive
- HTTPSettings
- OutlierDetection
- TLSSettings
- TLSmode
Source File: github.com/solo-io/supergloo/api/external/istio/networking/v1alpha3/destination_rule.proto
DestinationRule
DestinationRule
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:
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
loadBalancer:
simple: LEAST_CONN
Version specific policies can be specified by defining a named
subset
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).
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
Note: Policies specified for subsets will not take effect until a route rule explicitly sends traffic to this subset.
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.
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
"status": .core.solo.io.Status
"metadata": .core.solo.io.Metadata
"host": string
"trafficPolicy": .istio.networking.v1alpha3.TrafficPolicy
"subsets": []istio.networking.v1alpha3.Subset
"configScope": .istio.networking.v1alpha3.ConfigScope
Field | Type | Description | Default |
---|---|---|---|
status |
.core.solo.io.Status | Status indicates the validation status of this resource. Status is read-only by clients, and set by supergloo during validation | |
metadata |
.core.solo.io.Metadata | Metadata contains the object metadata for this resource | |
host |
string |
REQUIRED. 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. | |
trafficPolicy |
.istio.networking.v1alpha3.TrafficPolicy | Traffic policies to apply (load balancing policy, connection pool sizes, outlier detection). | |
subsets |
[]istio.networking.v1alpha3.Subset | One or more named sets that represent individual versions of a service. Traffic policies can be overridden at subset level. | |
configScope |
.istio.networking.v1alpha3.ConfigScope | The visibility setting associated with this DestinationRule. Set to PRIVATE if this destination rule should not be exported, i.e. restrict the applicability of this destination rule to only workloads in the same namespace as the destination rule. |
TrafficPolicy
Traffic policies to apply for a specific destination, across all destination ports. See DestinationRule for examples.
"loadBalancer": .istio.networking.v1alpha3.LoadBalancerSettings
"connectionPool": .istio.networking.v1alpha3.ConnectionPoolSettings
"outlierDetection": .istio.networking.v1alpha3.OutlierDetection
"tls": .istio.networking.v1alpha3.TLSSettings
"portLevelSettings": []istio.networking.v1alpha3.TrafficPolicy.PortTrafficPolicy
Field | Type | Description | Default |
---|---|---|---|
loadBalancer |
.istio.networking.v1alpha3.LoadBalancerSettings | Settings controlling the load balancer algorithms. | |
connectionPool |
.istio.networking.v1alpha3.ConnectionPoolSettings | Settings controlling the volume of connections to an upstream service | |
outlierDetection |
.istio.networking.v1alpha3.OutlierDetection | Settings controlling eviction of unhealthy hosts from the load balancing pool | |
tls |
.istio.networking.v1alpha3.TLSSettings | TLS related settings for connections to the upstream service. | |
portLevelSettings |
[]istio.networking.v1alpha3.TrafficPolicy.PortTrafficPolicy | 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. |
PortTrafficPolicy
Traffic policies that apply to specific ports of the service
"port": .istio.networking.v1alpha3.PortSelector
"loadBalancer": .istio.networking.v1alpha3.LoadBalancerSettings
"connectionPool": .istio.networking.v1alpha3.ConnectionPoolSettings
"outlierDetection": .istio.networking.v1alpha3.OutlierDetection
"tls": .istio.networking.v1alpha3.TLSSettings
Field | Type | Description | Default |
---|---|---|---|
port |
.istio.networking.v1alpha3.PortSelector | Specifies the port name or number of a port on the destination service on which this policy is being applied. Names must comply with DNS label syntax (rfc1035) and therefore cannot collide with numbers. If there are multiple ports on a service with the same protocol the names should be of the form |
|
loadBalancer |
.istio.networking.v1alpha3.LoadBalancerSettings | Settings controlling the load balancer algorithms. | |
connectionPool |
.istio.networking.v1alpha3.ConnectionPoolSettings | Settings controlling the volume of connections to an upstream service | |
outlierDetection |
.istio.networking.v1alpha3.OutlierDetection | Settings controlling eviction of unhealthy hosts from the load balancing pool | |
tls |
.istio.networking.v1alpha3.TLSSettings | TLS related settings for connections to the upstream service. |
Subset
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 VirtualService 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).
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
Note: Policies specified for subsets will not take effect until a 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 that supports multiple SNI hosts (e.g., an egress gateway), a subset without labels may be meaningful. In this case a traffic policy with TLSSettings can be used to identify a specific SNI host corresponding to the named subset.
"name": string
"labels": map<string, string>
"trafficPolicy": .istio.networking.v1alpha3.TrafficPolicy
Field | Type | Description | Default |
---|---|---|---|
name |
string |
REQUIRED. Name of the subset. The service name and the subset name can be used for traffic splitting in a route rule. | |
labels |
map<string, string> |
Labels apply a filter over the endpoints of a service in the service registry. See route rules for examples of usage. | |
trafficPolicy |
.istio.networking.v1alpha3.TrafficPolicy | 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. |
LoadBalancerSettings
Load balancing policies to apply for a specific destination. See Envoy’s load balancing documentation for more details.
For example, the following rule uses a round robin load balancing policy for all traffic going to the ratings service.
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
loadBalancer:
simple: ROUND_ROBIN
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.
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
The following example sets up locality weight for the ratings service Assume ratings service resides in “region1/zone1/” and “region1/zone2/”, and originating clusters also reside in “region1/zone1/” and “region1/zone2/”. This example specifies when clusters from “region1/zone1/” accessing ratings service, 80% of the traffic is shipped to “region1/zone1/” ratings service endpoints, and the rest 20% to “region1/zone2/*“.
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: bookinfo-ratings
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
loadBalancer:
localityWeightSettings:
- from: region1/zone1/*
to:
"region1/zone1/*": 80
"region1/zone2/*": 20
- from: region1/zone2/*
to:
"region1/zone1/*": 20
"region1/zone2/*": 80
"simple": .istio.networking.v1alpha3.LoadBalancerSettings.SimpleLB
"consistentHash": .istio.networking.v1alpha3.LoadBalancerSettings.ConsistentHashLB
"localityWeightSettings": []istio.networking.v1alpha3.LoadBalancerSettings.LocalityWeightSetting
Field | Type | Description | Default |
---|---|---|---|
simple |
.istio.networking.v1alpha3.LoadBalancerSettings.SimpleLB | ||
consistentHash |
.istio.networking.v1alpha3.LoadBalancerSettings.ConsistentHashLB | ||
localityWeightSettings |
[]istio.networking.v1alpha3.LoadBalancerSettings.LocalityWeightSetting | Explicitly assign 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. If duplicated settings are present, then the first one will take effect. |
ConsistentHashLB
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.
"httpHeaderName": string
"httpCookie": .istio.networking.v1alpha3.LoadBalancerSettings.ConsistentHashLB.HTTPCookie
"useSourceIp": bool
"minimumRingSize": int
Field | Type | Description | Default |
---|---|---|---|
httpHeaderName |
string |
Hash based on a specific HTTP header. | |
httpCookie |
.istio.networking.v1alpha3.LoadBalancerSettings.ConsistentHashLB.HTTPCookie | Hash based on HTTP cookie. | |
useSourceIp |
bool |
Hash based on the source IP address. | |
minimumRingSize |
int |
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. |
HTTPCookie
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.
"name": string
"path": string
"ttl": .google.protobuf.Duration
Field | Type | Description | Default |
---|---|---|---|
name |
string |
REQUIRED. Name of the cookie. | |
path |
string |
Path to set for the cookie. | |
ttl |
.google.protobuf.Duration | REQUIRED. Lifetime of the cookie. |
LocalityWeightSetting
Originating -> upstream cluster locality weight set, support wildcard matching ‘‘ ‘’ matches all localities ‘region1/*’ matches all zones in region1
"from": string
"to": map<string, int>
Field | Type | Description | Default |
---|---|---|---|
from |
string |
Originating locality, ‘/’ separated, e.g. ‘region/zone/sub_zone’. | |
to |
map<string, int> |
Upstream locality to loadbalancing weight map. The sum of all weights should be == 100. Should assign loadbalancing weight for all localities, otherwise the traffic are not routed following the percentage of weight. |
SimpleLB
Standard load balancing algorithms that require no tuning.
Name | Description |
---|---|
ROUND_ROBIN |
Round Robin policy. Default |
LEAST_CONN |
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. |
RANDOM |
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. |
PASSTHROUGH |
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. |
ConnectionPoolSettings
Connection pool settings for an upstream host. The settings apply to each individual host in the upstream service. See Envoy’s circuit breaker for more details. Connection pool settings can be applied at the TCP level as well as at HTTP level.
For example, the following rule sets a limit of 100 connections to redis service called myredissrv with a connect timeout of 30ms
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
"tcp": .istio.networking.v1alpha3.ConnectionPoolSettings.TCPSettings
"http": .istio.networking.v1alpha3.ConnectionPoolSettings.HTTPSettings
Field | Type | Description | Default |
---|---|---|---|
tcp |
.istio.networking.v1alpha3.ConnectionPoolSettings.TCPSettings | Settings common to both HTTP and TCP upstream connections. | |
http |
.istio.networking.v1alpha3.ConnectionPoolSettings.HTTPSettings | HTTP connection pool settings. |
TCPSettings
Settings common to both HTTP and TCP upstream connections.
"maxConnections": int
"connectTimeout": .google.protobuf.Duration
"tcpKeepalive": .istio.networking.v1alpha3.ConnectionPoolSettings.TCPSettings.TcpKeepalive
Field | Type | Description | Default |
---|---|---|---|
maxConnections |
int |
Maximum number of HTTP1 /TCP connections to a destination host. | |
connectTimeout |
.google.protobuf.Duration | TCP connection timeout. | |
tcpKeepalive |
.istio.networking.v1alpha3.ConnectionPoolSettings.TCPSettings.TcpKeepalive | If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives. |
TcpKeepalive
TCP keepalive.
"probes": int
"time": .google.protobuf.Duration
"interval": .google.protobuf.Duration
Field | Type | Description | Default |
---|---|---|---|
probes |
int |
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.) | |
time |
.google.protobuf.Duration | 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.) | |
interval |
.google.protobuf.Duration | The time duration between keep-alive probes. Default is to use the OS level configuration (unless overridden, Linux defaults to 75s.) |
HTTPSettings
Settings applicable to HTTP1.1/HTTP2/GRPC connections.
"http1MaxPendingRequests": int
"http2MaxRequests": int
"maxRequestsPerConnection": int
"maxRetries": int
Field | Type | Description | Default |
---|---|---|---|
http1MaxPendingRequests |
int |
Maximum number of pending HTTP requests to a destination. Default 1024. | |
http2MaxRequests |
int |
Maximum number of requests to a backend. Default 1024. | |
maxRequestsPerConnection |
int |
Maximum number of requests per connection to a backend. Setting this parameter to 1 disables keep alive. | |
maxRetries |
int |
Maximum number of retries that can be outstanding to all hosts in a cluster at a given time. Defaults to 3. |
OutlierDetection
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’s outlier detection for more details.
The following rule sets a connection pool size of 100 connections and 1000 concurrent HTTP2 requests, with no more than 10 req/connection to “reviews” service. In addition, it configures upstream hosts to be scanned every 5 mins, such that any host that fails 7 consecutive times with 5XX error code will be ejected for 15 minutes.
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
"consecutiveErrors": int
"interval": .google.protobuf.Duration
"baseEjectionTime": .google.protobuf.Duration
"maxEjectionPercent": int
"minHealthPercent": int
Field | Type | Description | Default |
---|---|---|---|
consecutiveErrors |
int |
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. | |
interval |
.google.protobuf.Duration | Time interval between ejection sweep analysis. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s. | |
baseEjectionTime |
.google.protobuf.Duration | 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. | |
maxEjectionPercent |
int |
Maximum % of hosts in the load balancing pool for the upstream service that can be ejected. Defaults to 10%. | |
minHealthPercent |
int |
Outlier detection will be enabled as long as the associated load balancing pool has at least min_health_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 default is 50%. |
TLSSettings
SSL/TLS related settings for upstream connections. See Envoy’s TLS context for more details. These settings are common to both HTTP and TCP upstreams.
For example, the following rule configures a client to use mutual TLS for connections to upstream database cluster.
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
The following rule configures a client to use TLS when talking to a foreign service whose domain matches *.foo.com.
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: tls-foo
spec:
host: "*.foo.com"
trafficPolicy:
tls:
mode: SIMPLE
The following rule configures a client to use Istio mutual TLS when talking to rating services.
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: ratings-istio-mtls
spec:
host: ratings.prod.svc.cluster.local
trafficPolicy:
tls:
mode: ISTIO_MUTUAL
"mode": .istio.networking.v1alpha3.TLSSettings.TLSmode
"clientCertificate": string
"privateKey": string
"caCertificates": string
"subjectAltNames": []string
"sni": string
Field | Type | Description | Default |
---|---|---|---|
mode |
.istio.networking.v1alpha3.TLSSettings.TLSmode | REQUIRED: Indicates whether connections to this port should be secured using TLS. The value of this field determines how TLS is enforced. | |
clientCertificate |
string |
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 . |
|
privateKey |
string |
REQUIRED if mode is MUTUAL . The path to the file holding the client’s private key. Should be empty if mode is ISTIO_MUTUAL . |
|
caCertificates |
string |
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’s certificate. Should be empty if mode is ISTIO_MUTUAL . |
|
subjectAltNames |
[]string |
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. | |
sni |
string |
SNI string to present to the server during TLS handshake. |
TLSmode
TLS connection mode
Name | Description |
---|---|
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 presenting client certificates for authentication. |
ISTIO_MUTUAL |
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 TLSSettings should be empty. |