Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท Traffic Management

Virtual Services and Destination Rules

Learn how VirtualService routes requests and DestinationRule defines subsets, load balancing and connection pools, and how the two work together.

Almost every Istio traffic feature is built from two resources working as a pair. A VirtualService answers "where should this request go?". A DestinationRule answers "now that it is going there, how should the proxy talk to it?". If you understand this pair, the rest of the chapter is variations.

All YAML here is read-only: Istio needs a cluster. The Python snippets are stand-ins for the matching and balancing logic, not Istio.

The setup

The shop's catalog has two deployments, labelled version: v1 and version: v2, behind one Kubernetes Service catalog. Without Istio, requests spread across all pods. With these two resources, you decide.

DestinationRule: subsets and policy

YAML
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: catalog
  namespace: shop
spec:
  host: catalog.shop.svc.cluster.local
  trafficPolicy:
    loadBalancer:
      simple: LEAST_REQUEST
    connectionPool:
      tcp:
        maxConnections: 100
      http:
        http2MaxRequests: 200
        maxRequestsPerConnection: 10
  subsets:
    - name: v1
      labels:
        version: v1
    - name: v2
      labels:
        version: v2
      trafficPolicy:
        loadBalancer:
          simple: ROUND_ROBIN
  • host is the destination service. Use the fully qualified name to avoid ambiguity across namespaces.
  • trafficPolicy at the top applies to every subset; a subset can override it.
  • loadBalancer.simple chooses the algorithm: ROUND_ROBIN, LEAST_REQUEST (default since newer releases), RANDOM, or PASSTHROUGH. consistentHash gives session affinity by header, cookie or source IP.
  • connectionPool limits connections and pending requests; it is also how circuit breaking begins (see chapter 7).
  • subsets give version names to groups of pods selected by label.

VirtualService: routing rules

YAML
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: catalog
  namespace: shop
spec:
  hosts:
    - catalog
  http:
    - route:
        - destination:
            host: catalog
            subset: v1

This sends all traffic for catalog to the v1 pods. Parts of the spec:

  • hosts: the names clients use. Inside the mesh a short name resolves in the VirtualService's namespace; at gateways use full DNS names.
  • http: an ordered list of rules. Each has optional match blocks and a route list of destinations with weight. The first matching rule wins, so put specific matches first and finish with a rule with no match as the default.
  • tcp and tls blocks route non-HTTP traffic by port or SNI.
  • gateways: which gateways the rules apply to; by default mesh, meaning all sidecars.
flowchart LR
    R["Request to catalog"] --> V{"VirtualService<br/>match rules"}
    V -->|"rule 1"| S1["subset v2"]
    V -->|"default"| S2["subset v1"]
    S1 --> D["DestinationRule<br/>policy and subsets"]
    S2 --> D
    D --> P["Pods"]

The VirtualService picks a destination and subset; the DestinationRule supplies what the subset means.

Timeouts and retries

Both live on the route and need no other resource:

YAML
http:
  - route:
      - destination: { host: catalog, subset: v1 }
    timeout: 2s
    retries:
      attempts: 2
      perTryTimeout: 500ms
      retryOn: connect-failure,refused-stream,503

timeout is the total budget; perTryTimeout limits each attempt. Chapter 7 returns to retries and their dangers.

Common mistakes

  • Subset without DestinationRule. The proxy has no such cluster; requests fail with 503 NR or UH. Apply the DestinationRule first.
  • Weights that do not sum to 100. Recent releases normalise them, but keep them explicit.
  • Host names. hosts: [catalog] is expanded relative to the namespace of the VirtualService, which can surprise you in multi-namespace meshes. Prefer the full name when in doubt.
  • Port names. A route is only L7 if the port is named for HTTP, see Sidecar Injection and Your First Mesh App.

Stand-in: a rule matcher

Here is a small model of "first matching rule wins" with a default, and of checking weights.

Python Stand-in: first matching rule wins

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: load balancing algorithms

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which resource defines the subsets v1 and v2?

    Subsets are label selectors declared in the DestinationRule; the VirtualService only refers to them.
  2. 2. In a VirtualService with several http rules, which one is used?

    Rules are evaluated in order; put specific matches first and a catch-all last.
  3. 3. A VirtualService routes to subset v3, which no DestinationRule defines. What is the likely result?

    The destination cluster does not exist; expect 503 responses until the subset is defined.
  4. 4. Where do you set a total request timeout?

    timeout and retries are fields of an http route.

Summary

  • VirtualService decides where a request goes; DestinationRule decides how to talk to the target.
  • Subsets are label selectors defined in DestinationRule.
  • HTTP rules are ordered; the first match wins, with an unconditional default last.
  • Timeouts and retries are route fields.
  • Always create the DestinationRule before routing to its subsets.

Next: Weighted Routing and Canary Releases