Configuring Destination Rules

1. Creating Destination Rules

Property	Description	Example
host	Destination host name for the rule	`reviews`
trafficPolicy	Defines traffic policies for the destination	`{ "loadBalancer": { "simple": "LEAST_CONN" } }`
subset	Defines a specific version or subset of the service	`{ "name": "v1", "labels": { "version": "v1" } }`

Example: Basic Destination Rule

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: reviews
spec:
  host: reviews
  trafficPolicy:
    loadBalancer:
      simple: LEAST_CONN

Example: Destination Rule with Subsets

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: reviews
spec:
  host: reviews
  subsets:
  - name: v1
    labels:
      version: v1
  - name: v2
    labels:
      version: v2

2. Configuring Traffic Policies

Property	Description	Values	Notes
loadBalancer	Defines the load balancing policy for traffic to a service	`simple`, `leastConn`, `random`, `consistentHash`	Default is `simple`
connectionPool	Configures connection pool settings for outbound traffic	`tcp`, `http`	Allows control over idle timeouts and max connections
outlierDetection	Defines how to detect and handle outlier hosts	`consecutiveErrors`, `interval`, `baseEjectionTime`	Used to remove unhealthy hosts from the load balancing pool
timeout	Configures timeout settings for HTTP requests	`http`, `connectTimeout`	Defaults to 15 seconds for HTTP requests

Example: Configuring Load Balancing Policy

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: my-destination-rule
spec:
  host: my-service
  trafficPolicy:
    loadBalancer:
      simple: LEAST_CONN

Example: Configuring Connection Pool

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: my-destination-rule
spec:
  host: my-service
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 1024
        connectTimeout: 30ms
      http:
        http1MaxPendingRequests: 100
        http2MaxRequests: 1000

Example: Configuring Outlier Detection

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: my-destination-rule
spec:
  host: my-service
  trafficPolicy:
    outlierDetection:
      consecutiveErrors: 5
      interval: 10s
      baseEjectionTime: 30s

3. Defining Service Subsets

Property	Description	Values	Notes
name	Unique identifier for the subset	`string`	Required field
labels	Labels to select the subset of pods	`map<string, string>`	Used for routing rules
trafficPolicy	Override global traffic policy for this subset	`object`	Optional, nested object

Example: Defining a service subset

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: reviews
spec:
  host: reviews
  subsets:
  - name: v1
    labels:
      version: v1
  - name: v2
    labels:
      version: v2

4. Implementing Outlier Detection

Property	Values	Description
consecutiveErrors	`5`	Number of consecutive 5xx errors to mark a host as unhealthy.
interval	`10s`	Time interval to consider for outlier detection.
baseEjectionTime	`30s`	Initial ejection time for a host before exponential backoff.
maxEjectionPercent	`10%`	Maximum percentage of hosts to eject from a service.

Example: Outlier Detection Configuration

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: my-destination-rule
spec:
  host: my-service
  trafficPolicy:
    outlierDetection:
      consecutiveErrors: 5
      interval: 10s
      baseEjectionTime: 30s
      maxEjectionPercent: 10

Note: Outlier detection is a powerful feature for improving resilience in service-to-service communication. It helps isolate failing services to prevent cascading failures.

5. Configuring Client-Side TLS Settings

Property	Description	Values	Notes
tls.mode	Specifies the TLS mode to use for client-side connections	`DISABLE`, `ISTIO_MUTUAL`, `MUTUAL`, `PASSTHROUGH`	Default is `ISTIO_MUTUAL` when mTLS is enabled
tls.clientCertificate	Certificate file path for client TLS authentication	`string`	Required when `tls.mode` is `MUTUAL`
tls.privateKey	Private key file path for client TLS authentication	`string`	Required when `tls.mode` is `MUTUAL`
tls.caCertificates	CA certificate file path to validate server certificates	`string`	Required when `tls.mode` is `MUTUAL` or `PASSTHROUGH`
tls.sni	SNI (Server Name Indication) to use for TLS handshake	`string`	Optional, used for hostname matching in TLS

Example: Client TLS Configuration

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: client-tls-config
spec:
  host: api.example.com
  trafficPolicy:
    tls:
      mode: MUTUAL
      clientCertificate: /etc/certs/client.crt
      privateKey: /etc/certs/client.key
      caCertificates: /etc/certs/ca.crt
      sni: api.example.com

6. Setting Connection Pool Limits

Property	Description	Values	Notes
connectionPool.http	HTTP connection pool settings	`{}`	Configures HTTP connection pool limits
connectionPool.http.http1MaxPendingRequests	Maximum pending HTTP/1.1 requests	`100`	Default value for max pending requests
connectionPool.http.http2MaxRequests	Maximum pending HTTP/2 requests	`1000`	Default value for max pending HTTP/2 requests
connectionPool.http.maxRequestsPerConnection	Maximum requests per connection	`1000`	Default value for max requests per connection
connectionPool.http.maxRetries	Maximum retries for failed requests	`3`	Default value for max retries
connectionPool.tcp	TCP connection pool settings	`{}`	Configures TCP connection pool limits
connectionPool.tcp.maxConnections	Maximum TCP connections	`1024`	Default value for max TCP connections
connectionPool.tcp.connectTimeout	Connection timeout for TCP	`30ms`	Default value for TCP connect timeout

Example: Configuring Connection Pool Limits

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: my-destination-rule
spec:
  host: example.com
  connectionPool:
    http:
      http1MaxPendingRequests: 200
      http2MaxRequests: 1500
      maxRequestsPerConnection: 2000
      maxRetries: 5
    tcp:
      maxConnections: 2048
      connectTimeout: 60ms

7. Implementing Locality Load Balancing

Property	Values	Description
localityLbSetting	`DISABLED`, `ENABLED`	Controls whether locality-based load balancing is enabled.
localityLbSetting.failover	`failover`	Defines failover behavior between localities.
localityLbSetting.failover.from	`region`, `zone`, `subzone`	Source locality for failover.
localityLbSetting.failover.to	`region`, `zone`, `subzone`	Target locality for failover.

Example: Locality Load Balancing Configuration

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: example-destination-rule
spec:
  host: example-service
  trafficPolicy:
    localityLbSetting:
      failover:
        from: zone
        to: region

Note: Locality load balancing requires that services are deployed across multiple zones or regions to be effective.

8. Managing Consistent Hash Configuration

Property	Description	Values	Notes
consistentHash	Enables consistent hashing for traffic routing	`httpCookie`, `httpHeader`, `httpQueryParameter`, `tcp`	Used to ensure consistent routing of requests to the same destination
httpCookie	Defines cookie-based consistent hashing	`name`, `ttl`	Applies to HTTP traffic only
httpHeader	Defines header-based consistent hashing	`name`	Applies to HTTP traffic only
httpQueryParameter	Defines query parameter-based consistent hashing	`name`	Applies to HTTP traffic only
tcp	Defines TCP-based consistent hashing	`sourceIp`	Applies to TCP traffic only

Example: Consistent Hash Configuration

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: example-destination-rule
spec:
  host: example-service
  trafficPolicy:
    consistentHash:
      httpCookie:
        name: user-session
        ttl: 1h

Note: Consistent hashing ensures that requests with the same key (e.g., session ID) are consistently routed to the same destination, which is useful for stateful services.

9. Configuring Port-Level Settings

Property	Description	Values	Notes
port.number	Specifies the port number to which traffic is directed	`80`, `443`, `8080`	Must match a port exposed by the service
port.name	Name of the port (e.g., http, https)	`http`, `https`	Used for service discovery and routing
port.protocol	Protocol used for traffic on this port	`TCP`, `HTTP`, `HTTPS`, `GRPC`	Must align with the service's actual protocol

Example: Port-Level Configuration

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: example-destination-rule
spec:
  host: example-service
  trafficPolicy:
    portLevelSettings:
    - port:
        number: 80
      connectionPool:
        http:
          maxRequestsPerConnection: 100

10. Managing Destination Rule Precedence

Precedence Level	Description	Scope	Example Use Case
0	Global default rules applied to all services	Cluster-wide	Setting up default timeouts and retries for all services in the mesh
1	Namespace-level rules overriding global defaults	Namespace	Applying specific circuit breaker settings to all services in a namespace
2	Service-specific rules overriding namespace rules	Service	Configuring specific load balancing for a particular service endpoint
3	Subset-specific rules overriding service rules	Subset	Applying different retry policies for specific subsets of a service (e.g., canary vs stable)

Example: Setting Precedence with Namespace-Level Rule

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: namespace-destination-rule
  namespace: production
spec:
  host: backend-service
  trafficPolicy:
    connectionPool:
      http:
        maxRequestsPerConnection: 10

Note: Precedence levels ensure that more specific configurations take effect over broader ones, allowing fine-grained control of traffic policies.

11. Implementing Destination Rule Merging

Example: Basic Destination Rule Merge

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: reviews-merge
spec:
  host: reviews
  trafficPolicy:
    connectionPool:
      http:
        http1MaxPendingRequests: 10
        maxRequestsPerConnection: 5
    outlierDetection:
      consecutiveErrors: 3
      interval: 10s
      baseEjectionTime: 15m

Property	Description	Values	Notes
host	Destination service name	`reviews`	Must match the service name in the mesh
trafficPolicy.connectionPool.http	HTTP connection pool settings	`http1MaxPendingRequests`, `maxRequestsPerConnection`	Controls connection reuse and pending requests
trafficPolicy.outlierDetection	Outlier detection configuration	`consecutiveErrors`, `interval`, `baseEjectionTime`	Determines how to handle unhealthy endpoints

Note: Merging is handled automatically by Istio based on the host field and matching labels.

Warning: Ensure that all DestinationRule resources targeting the same host do not conflict in their configurations.

Key Points for Merging

Merge occurs when multiple DestinationRule resources target the same host.
Settings from all matching rules are merged, with the last rule taking precedence in case of conflicts.
Use labels to scope rules to specific subsets or versions of a service.

12. Troubleshooting Destination Rule Issues

Example: Misconfigured Traffic Policy

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: example-dr
spec:
  host: example-service
  trafficPolicy:
    connectionPool:
      http:
        maxRequestsPerConnection: 10
        maxRetries: 3
    outlierDetection:
      consecutiveErrors: 5
      interval: 10s
      baseEjectionTime: 30s

Issue	Potential Cause	Solution
5xx Errors	Service overload or misconfigured timeout	Adjust `connectionPool` and `timeout` settings
Connection Timeouts	Service not responding within timeout limits	Increase `http` timeout values in `trafficPolicy`
503 Service Unavailable	Outlier detection ejecting healthy endpoints	Review `outlierDetection` configuration and adjust thresholds
High Latency	Improper load balancing or connection pooling	Optimize `loadBalancer` and `connectionPool` settings

Note: Use istioctl proxy-config to inspect the actual configuration applied to proxies.

Warning: Misconfigured outlierDetection can cause cascading failures by ejecting all endpoints.

Common Troubleshooting Steps

Verify DestinationRule is applied to the correct service
Check proxy logs for error messages related to connection or timeout
Validate that traffic policies align with service capabilities
Use istioctl analyze to detect configuration issues