# Istio Patterns: Traffic Splitting in Kubernetes (Header/Cookie Based)

> How to split traffic in Kubernetes with Istio based on request headers, tutorial, and examples with source code.

- Source: https://www.itwonderlab.com/istio-patterns-traffic-splitting-in-kubernetes-header-based/
- Published: 2019-05-27
- Updated: 2026-10-05
- Author: Javier Ruiz Jiménez (https://www.javierruizjimenez.com/)
- Site: IT Wonder Lab (https://www.itwonderlab.com/)

---

## Header Based Traffic Splitting Using Istio

> [!NOTE]
> This tutorial was written for Istio 1.x (2019-2020) on a local cluster. The ideas (gateway, virtual service, destination rule, labels as subsets) are still valid, but current Istio releases use the API version `networking.istio.io/v1` and different installation profiles, and the Kubernetes Gateway API is the recommended way to configure ingress. Check the [Istio documentation](https://istio.io/latest/docs/) for the version you install.

Using Istio it is possible to distribute the traffic load using a request or client header as a switch to decide where to send the traffic. It can be useful in many situations like:

-   **Testing a new release**: a request that includes a special header is sent to access the new release.
-   **Differentiating logged-in users from anonymous**: looking for the presence of a cookie that is set when the user is authenticated can be used to redirect all authenticated users to a different back-end.
-   **Trying a new interface**: Redirect users to a new interface during beta testing by placing a client cookie.

This tutorial shows how to define the needed Istio resources to distribute traffic based on the presence of a cookie or a header.

### Prerequisites

The examples shown in this Istio tutorial can be used in any Kubernetes cluster with Istio installed. If you need to run a full and free Kubernetes cluster on your development environment, please see my previous tutorials:

-   Install a [Kubernetes Cluster with Vagrant and Ansible (without Minikube)](https://www.itwonderlab.com/ansible-kubernetes-vagrant-tutorial/)
-   [Install Istio on Kubernetes under VirtualBox](https://www.itwonderlab.com/istio-in-local-kubernetes/)

You will also need the Color web application to follow the example, it is a very small and simple application developed in Go that changes the background color based on the value of an environment variable.

![Web browser showing a web page with green background and the content of the request](https://www.itwonderlab.com/media/2019/05/K8S_NodePort_ColorApp.png "Using a header to route a request in istio for A/B testing or new releases")

See [Istio Patterns: Traffic Splitting in Kubernetes (Canary Release)](https://www.itwonderlab.com/istio-patterns-traffic-splitting-in-kubernetes/) for instructions on how to build the application.

You can download the source code from [IT Wonder Lab git repository](https://github.com/itwonderlab/istio-patterns), build the application, and create your own Docker image, or use a prebuilt image from the [IT Wonder Lab Docker public repository](https://hub.docker.com/u/itwonderlab).

### Istio Definition for Header Traffic Routing

The `color-istio-gw-client-header.yaml` defines 4 resources to accomplish an Istio Header Traffic Routing Deployment of the Color application:

![Nodeport Gateway Virtual Service examining a Header, Destination Rule and Service](https://www.itwonderlab.com/media/2019/05/ansible-kubernetes-vagrant-tutorial-Istio-Header.png "Using Istio for traffic routing based on a Header")

To make a header-based routing decision in Istio only a single configuration element needs to be changed, the Istio Virtual Service.

**Istio Virtual Service**

It is a networking.istio.io/v1alpha3 VirtualService, shown with a yellow background on the above diagram.

The name of the Istio Virtual Service has been changed so that the previous Canary Deployment can still work and is not replaced by this new definition.

The new **color-is-vs-header** Istio Virtual Service is defined as:

```json title="color-istio-gw-client-header.yaml color-is-vs-header"
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: color-is-vs-header
spec:
  hosts:
  - "*"
  gateways:
  - color-is-gw
  http:
  - match:
    - uri:
        prefix: /header
      headers:
        want-color:
          exact: green
    route:
    - destination:
        host: color-service #Name of the service
        subset: green-sub
  - match:
    - uri:
        prefix: /header
    route:
    - destination: #Default (if match is false)
        host: color-service #Name of the service
        subset: blue-sub
```

The “hosts” attribute is used to **match traffic with** any host header (represented with \*).

The “http” attribute defines that this Virtual Service applies to HTTP traffic.

Indentation of match sections and route attributes are used to create an **Istio Routing decision tree**, in our header routing example, the match sections have the same indentation, meaning that the first match section will be evaluated, and if all conditions are true, the route will be applied. If any of the conditions fail, the next match section will be evaluated.

**Istio decision tree**:

The first “match” section will:

1.  Select the traffic whose:
    -   **URI** has a prefix /header AND
    -   a **header** is present with the name “want-color” and the value is exactly “green”
2.  Route the selected traffic to the subset green-sub of the color-service.
3.  End evaluation of Istio Virtual Service

The second “match” section will only be evaluated if the first section is not true, it will:

1.  Select the traffic whose:
    1.  **URI** has a prefix /header AND
2.  Route the selected traffic to the subset blue-sub of the color-service.
3.  End evaluation of Istio Virtual Service

The Istio Gateway, Kubernetes Service color-service, and Istio Destination Rule are the same as the ones defined for the Canary Deployment, shown here as a reference:

-   **Istio Gateway** (networking.istio.io/v1alpha3 Gateway): uses the existing ingressgateway created when Istio was deployed to accept HTTP traffic at port 80 from any host (\*).
-   **Istio Destination Rule** (networking.istio.io/v1alpha3 DestinationRule): defines subsets of a known service, in our example defines two subsets of the **color-service** service or host (in Istio, the services are called the host):
    -   **blue-sub**: corresponds to the service **color-service** with a label **color** equal to **blue.**
    -   **green-sub**: corresponds to the service **color-service** with a label **color** equal to **green.**
-   **Kubernetes Service** **color-service**: creates a cluster service named “**color-service**“, that receives traffic at port 8000 and sends it to port 8080 of the containers (the port exposed by the Docker images of the Color Application).

Create the objects in the Kubernetes Cluster with:

```bash
jruiz@XPS13:~/../istio-patterns$ kubectl apply -f color-istio-gw-client-header.yaml
```

Open a browser and visit the URL [http://192.168.50.11:31380/header/](http://192.168.50.11:31380/header/)

The background of the page will be always blue.

In order to access the green version, a client header needs to be added. If using Google Chrome a header can be added with the extension [ModHeader.](https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj)

Add the header want-color with the value green.

![set istio header](https://www.itwonderlab.com/media/2019/05/set-istio-header.png)

Reload the URL [http://192.168.50.11:31380/header/](http://192.168.50.11:31380/header/) to see the green version:

![Web broser windows showing a green page with the contents of the Request](https://www.itwonderlab.com/media/2019/05/Istio-Header-Green.png "Istio receiving a header indicating the color to show (application to route to)")

Delete the header or change its name or value to go back to the blue version.

## Use a Cookie for Istio Routing

In order to have **cookie-based Routing decisions in Istio**, only a single configuration element needs to be changed, the Istio Virtual Service.

The `color-istio-gw-client-cookie.yaml` includes all the needed Istio objects.

The name of the Istio Virtual Service has been changed so that the previous Header-Based Deployment can still work and is not replaced by this new definition.

The new **color-is-vs-cookie** Istio Virtual Service is defined as:

```json title="color-istio-gw-client-cookie.yaml"
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: color-is-vs-cookie
spec:
  hosts:
  - "*"
  gateways:
  - color-is-gw
  http:
  - match:
    - uri:
        prefix: /cookie
      headers:
        cookie:
          regex: ^(.\*?;)?(my-color=green)(;.\*)?$
    route:
    - destination:
        host: color-service #Name of the service
        subset: green-sub
  - match:
    - uri:
        prefix: /cookie
    route:
    - destination: #Default (if match is false)
        host: color-service #Name of the service
        subset: blue-sub
```

The new **Istio decision tree** checks for the existence of a cookie. Cookies are not much different than other client headers, the only difference is that a regular expression is needed to find the desired cookie inside the cookie header.

The first “match” section will:

1.  Select the traffic whose:
    -   **URI** has a prefix /header AND
    -   a **header** is present with the name “cookie” and value color=green. A regular expression *^(.\\\*?;)?(my-color=green)(;.\\\*)?$* is used to test the condition.
2.  Route the selected traffic to the subset green-sub of the color-service.
3.  End evaluation of Istio Virtual Service

The second “match” section will only be evaluated if the first section is not true, it will:

1.  Select the traffic whose:
    1.  **URI** has a prefix /header AND
2.  Route the selected traffic to the subset blue-sub of the color-service.
3.  End evaluation of Istio Virtual Service

In order to access the green version, a cookie needs to be added. If using Google Chrome a cookie can be added with the extension [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm).

Add the cookie my-color with the value green and reload the URL [http://192.168.50.11:31380/header/](http://192.168.50.11:31380/header/) to see the green version.

![Webbroser windows showing a green page with the contents of the Request](https://www.itwonderlab.com/media/2019/05/Istio-Cookie-Green.png "Two cookies are shown as part of the Request in an Istio service mesh")

The screenshot of the Color Applications shows, highlighted in blue, two Cookies, one of the cookies is the my-color=green cookie set by us using the Google Chrome extension Cookie-Editor and the other cookie color=green was set by the application and sent to the client.