Demo Destination Rules

DestinationRules in Istio enable advanced traffic management for services. They define subsets used for traffic splitting, configure load balancing and connection pools, enable circuit breaking and outlier detection, and set client TLS modes. In this guide we’ll walk through a common workflow: deploying two versions of a HelloWorld service, defining subsets via a DestinationRule, and splitting traffic with a VirtualService.

Prerequisites

Verify Istio sidecar injection is enabled for your namespace(s):

kubectl get ns --show-labels

Example output:

NAME              STATUS   AGE   LABELS
default           Active   25m   istio-injection=enabled,kubernetes.io/metadata.name=default
istio-system      Active   22m   kubernetes.io/metadata.name=istio-system
kube-node-lease   Active   25m   kubernetes.io/metadata.name=kube-node-lease
kube-public       Active   25m   kubernetes.io/metadata.name=kube-public
kube-system       Active   25m   kubernetes.io/metadata.name=kube-system

Namespaces must be labeled for Istio sidecar injection (or the pods must have the sidecar injected) for VirtualService/DestinationRule routing to take effect across namespaces.

Deploy the HelloWorld sample (v1 and v2)

Deploy two versions of a HelloWorld application (v1 and v2). Confirm the pods are running and each pod shows 2/2 (application container + Envoy sidecar):

kubectl get pods --show-labels

Example output:

NAME                              READY   STATUS    RESTARTS   AGE     LABELS
helloworld-v1-7459d7b54b-wxfnj    2/2     Running   0          2m31s   app=helloworld,version=v1,...
helloworld-v2-654d97458-twmkh     2/2     Running   0          2m31s   app=helloworld,version=v2,...

Inspect the service and pod labels — DestinationRule subsets will match pod labels (for example version: v1 and version: v2):

kubectl get svc --show-labels
kubectl get pods --show-labels

Example abbreviated output:

# service
NAME         TYPE        CLUSTER-IP       PORT(S)    LABELS
helloworld   ClusterIP   10.105.208.216   5000/TCP   app=helloworld,service=helloworld

# pods
helloworld-v1-7459d7b54b-wxfnj   2/2  Running  app=helloworld,version=v1,...
helloworld-v2-654d97458-twmkh    2/2  Running  app=helloworld,version=v2,...

Create a test namespace and test client

Create a separate namespace for testing and enable Istio injection there. VirtualService/DestinationRule behavior depends on whether the communicating namespaces have sidecar injection enabled.

kubectl create ns test
kubectl label namespace test istio-injection=enabled

Run a simple test pod in the test namespace (a lightweight curl image that stays running so you can exec into it):

kubectl run test --image=curlimages/curl -n test --restart=Never --command -- sleep 3600
kubectl get pods -n test

Example:

NAME   READY   STATUS    RESTARTS   AGE
test   2/2     Running   0          3s

Exec into the test pod (or run a one-off command) to curl the HelloWorld service in the default namespace:

kubectl exec -ti -n test test -- curl helloworld.default.svc:5000/hello

With no Istio routing yet, responses will be balanced by Kubernetes/Envoy defaults and you should see responses from either v1 or v2.

Create a DestinationRule (subsets)

DestinationRules declare subsets that map to pod labels. Create a DestinationRule for the helloworld host that defines v1 and v2 subsets:

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: hello-world-dr
  namespace: default
spec:
  host: helloworld
  subsets:
    - name: v1
      labels:
        version: v1
    - name: v2
      labels:
        version: v2

Apply the DestinationRule and confirm it’s created:

kubectl apply -f dr.yaml
kubectl get destinationrules.networking.istio.io

Example output:

NAME            HOST        AGE
hello-world-dr  helloworld  5s

Note: A DestinationRule alone does not split traffic; subsets simply define targets. You need a VirtualService to route between those subsets.

Create a VirtualService to split traffic

Create a VirtualService that references the subsets declared in your DestinationRule. This example splits traffic 50/50 between v1 and v2:

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: hello-world-vs
  namespace: default
spec:
  hosts:
    - helloworld
  http:
    - match:
        - uri:
            prefix: /
      route:
        - destination:
            host: helloworld.default.svc.cluster.local
            port:
              number: 5000
            subset: v1
          weight: 50
        - destination:
            host: helloworld.default.svc.cluster.local
            port:
              number: 5000
            subset: v2
          weight: 50

Apply the VirtualService and verify it exists:

kubectl apply -f vs.yaml
kubectl get virtualservices.networking.istio.io

Example output:

NAME             HOSTS         AGE
hello-world-vs   [helloworld]  5s

Test the routing

From the test pod, run several requests to observe traffic being split between v1 and v2:

kubectl exec -ti -n test test -- /bin/sh -c 'for i in 1 2 3 4 5 6 7; do curl -s helloworld.default.svc:5000/hello; echo; done'

Example responses:

Hello version: v2, instance: helloworld-v2-654d97458-twmkh
Hello version: v1, instance: helloworld-v1-7459d7b54b-wxfnj
Hello version: v2, instance: helloworld-v2-654d97458-twmkh
...

Adjust weights for traffic distribution

To change the split, update the weight fields in the VirtualService. For example, to route 95% to v1 and 5% to v2, modify the route section:

# update vs.yaml with these weights
        - destination:
            host: helloworld.default.svc.cluster.local
            port:
              number: 5000
            subset: v1
          weight: 95
        - destination:
            host: helloworld.default.svc.cluster.local
            port:
              number: 5000
            subset: v2
          weight: 5

Apply the updated VirtualService:

kubectl apply -f vs.yaml

Re-run the curl loop in the test pod; you should observe mostly v1 responses. View the final resource files for reference:

cat vs.yaml
cat dr.yaml

DestinationRule features (summary)

DestinationRules cover multiple traffic-management concerns. Use the table below as a quick reference.

Feature	Purpose	Example/Notes
Subsets	Define named groups of endpoints (by labels) for fine-grained routing	`subset: v1` selects pods labeled `version: v1`
Connection pools	Control TCP/HTTP connection reuse and limits	Set `trafficPolicy.connectionPool` to limit `maxConnections`
Load balancing	Choose LB algorithm per host or per subset	`simple: LEAST_REQUEST`, `ROUND_ROBIN`, etc.
Outlier detection / circuit breaking	Eject unhealthy hosts and limit requests	`outlierDetection` with `consecutive5xxErrors` and `baseEjectionTime`
Client TLS	Configure TLS modes between client and destination	`tls.mode: MUTUAL`, `SIMPLE`, `DISABLE`, `ISTIO_MUTUAL`

Example DestinationRule snippets

Connection pool example (TCP):

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: bookinfo-redis
spec:
  host: myredisrv.prod.svc.cluster.local
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 100
        connectTimeout: 30ms
        tcpKeepalive:
          time: 7200s
          interval: 75s

Load-balancer and subset-specific trafficPolicy:

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: bookinfo-ratings
spec:
  host: ratings.prod.svc.cluster.local
  trafficPolicy:
    loadBalancer:
      simple: LEAST_REQUEST
  subsets:
    - name: testversion
      labels:
        version: v3
      trafficPolicy:
        loadBalancer:
          simple: ROUND_ROBIN

Outlier detection / circuit breaker:

apiVersion: networking.istio.io/v1beta1
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:
      consecutive5xxErrors: 7
      interval: 5m
      baseEjectionTime: 15m

Client TLS (MUTUAL):

apiVersion: networking.istio.io/v1beta1
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

Client TLS (SIMPLE):

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: tls-foo
spec:
  host: "*.foo.com"
  trafficPolicy:
    tls:
      mode: SIMPLE

Client TLS (Istio mTLS for ratings service):

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: ratings-istio-mtls
spec:
  host: ratings.prod.svc.cluster.local
  trafficPolicy:
    tls:
      mode: MUTUAL

The image shows a webpage from Istio documentation detailing the TLS connection modes, with a table outlining different modes such as DISABLE, SIMPLE, MUTUAL, and ISTIO_MUTUAL alongside their descriptions.

Next steps and practice tips

Practice creating subsets and VirtualServices that reference those subsets to get comfortable with weight-based splitting.
Experiment with trafficPolicy fields (connectionPool, loadBalancer, outlierDetection) to observe their operational effects.
Use different TLS modes when securing connections between services and test with mutual TLS where appropriate.

References

Introduction

Installation & Configuration

Traffic Management

Securing Workloads

Troubleshooting

Conclusion

Demo Destination Rules

Prerequisites

Deploy the HelloWorld sample (v1 and v2)

Create a test namespace and test client

Create a DestinationRule (subsets)

Create a VirtualService to split traffic

Test the routing

Adjust weights for traffic distribution

DestinationRule features (summary)

Example DestinationRule snippets

Next steps and practice tips

Watch Video

Practice Lab

​Prerequisites

​Deploy the HelloWorld sample (v1 and v2)

​Create a test namespace and test client

​Create a DestinationRule (subsets)

​Create a VirtualService to split traffic

​Test the routing

​Adjust weights for traffic distribution

​DestinationRule features (summary)

​Example DestinationRule snippets

​Next steps and practice tips

Watch Video

Practice Lab

Prerequisites

Deploy the HelloWorld sample (v1 and v2)

Create a test namespace and test client

Create a DestinationRule (subsets)

Create a VirtualService to split traffic

Test the routing

Adjust weights for traffic distribution

DestinationRule features (summary)

Example DestinationRule snippets

Next steps and practice tips