DestinationRule

Kubernetes hub

An Istio custom resource that defines policies applied to traffic after routing decisions are made. It groups pods into named subsets (for use in VirtualService), and configures connection pooling, circuit breaking, and load balancing per destination.

What is a DestinationRule

A DestinationRule answers two questions:

Which pods belong to which version (for traffic splitting)?
What policies apply to connections reaching this service?

A VirtualService decides where to send traffic. A DestinationRule defines what those destinations look like and how connections to them should behave.

TEXT

VirtualService: "send 5% to subset v2"
DestinationRule: "subset v2 means pods with label version=v2,
                  and connections to that subset have a circuit breaker
                  that trips after 5 consecutive errors"

Defining Subsets

YAML

apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: orders-service
  namespace: production
spec:
  host: orders-service
  subsets:
    - name: v1
      labels:
        version: "v1"    ## selects pods with this label
    - name: v2
      labels:
        version: "v2"    ## selects pods with this label

The labels field matches against pod labels. Pods tagged version: v1 belong to the v1 subset. This is how Istio knows which physical pods to send traffic to when a VirtualService says "route to v1."

Traffic Policy - Applies to All Subsets

YAML

spec:
  host: orders-service
  trafficPolicy:           ## applies to all subsets unless overridden
    connectionPool:
      http:
        http1MaxPendingRequests: 100
        maxRequestsPerConnection: 10
    outlierDetection:
      consecutive5xxErrors: 5
      interval: 10s
      baseEjectionTime: 30s
      maxEjectionPercent: 50
  subsets:
    - name: v1
      labels:
        version: "v1"
    - name: v2
      labels:
        version: "v2"
      trafficPolicy:       ## override: v2 gets stricter circuit breaking
        outlierDetection:
          consecutive5xxErrors: 3
          baseEjectionTime: 60s

Load Balancing Policy

YAML

trafficPolicy:
  loadBalancer:
    simple: LEAST_CONN    ## ROUND_ROBIN, LEAST_CONN, RANDOM, PASSTHROUGH

TEXT

ROUND_ROBIN:   default, distribute evenly
LEAST_CONN:    send to pod with fewest active connections
RANDOM:        random pod selection
PASSTHROUGH:   no load balancing, connect to destination directly

DestinationRule for mTLS

You can also use DestinationRule to configure client-side mTLS settings:

YAML

trafficPolicy:
  tls:
    mode: ISTIO_MUTUAL    ## use Istio's mTLS for this destination

Remember
DestinationRule subsets use pod label selectors - not Deployment names or Service names. The label you choose must be present on the pod template in the Deployment spec. If pods do not have the label, they will not be selected into any subset and traffic routing will fail.

Tip
Apply DestinationRule BEFORE VirtualService when deploying a new canary. If the VirtualService is applied first and references a subset that the DestinationRule has not defined yet, Istio returns 503 errors on all matching routes until the DestinationRule arrives.

Frequently Asked Questions

How does a DestinationRule relate to a VirtualService — do you need both?

Yes, they're two halves of Istio's traffic management: a VirtualService decides *where* a request goes (which subset, based on headers, weights, or paths), and a DestinationRule defines *what those subsets are* and how connections to them behave once chosen — load balancing algorithm, connection pool limits, outlier detection for circuit breaking. A canary rollout typically needs both: DestinationRule to define a 'v2' subset by pod label, VirtualService to route 10% of traffic to it.

What's a common DestinationRule mistake that causes confusing 503s?

Referencing a subset in a VirtualService that was never defined in a matching DestinationRule — Envoy will return 503 UF (upstream failure) with no obvious error pointing at the misconfiguration. Also watch outlier detection settings: an aggressively low `consecutiveErrors` threshold can eject healthy pods from the load balancing pool during a brief blip, making a minor issue look like a full outage. Always check `istioctl analyze` before assuming an application-level bug.