Request Routing

This task shows you how to route requests dynamically to multiple versions of a microservice.

Istio includes beta support for the Kubernetes Gateway API and intends to make it the default API for traffic management in the future. The following instructions allow you to choose to use either the Gateway API or the Istio configuration API when configuring traffic management in the mesh. Follow instructions under either the Gateway API or Istio APIs tab, according to your preference.

Note that this document uses the Gateway API to configure internal mesh (east-west) traffic, i.e., not just ingress (north-south) traffic. Configuring internal mesh traffic is an experimental feature of the Gateway API, currently under development. If using the Gateway API instructions, before proceeding make sure to:

  1. Install the experimental version of the Gateway API CRDs:

    1. $ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v1.0.0" | kubectl apply -f -

  2. Configure Istio to read the alpha Gateway API resources by setting the PILOT_ENABLE_ALPHA_GATEWAY_API environment variable to true when installing Istio:

    1. $ istioctl install --set values.pilot.env.PILOT_ENABLE_ALPHA_GATEWAY_API=true --set profile=minimal -y

Before you begin

About this task

The Istio Bookinfo sample consists of four separate microservices, each with multiple versions. Three different versions of one of the microservices, reviews, have been deployed and are running concurrently. To illustrate the problem this causes, access the Bookinfo app’s /productpage in a browser and refresh several times. The URL is http://$GATEWAY_URL/productpage, where $GATEWAY_URL is the External IP address of the ingress, as explained in the Bookinfo doc.

You’ll notice that sometimes the book review output contains star ratings and other times it does not. This is because without an explicit default service version to route to, Istio routes requests to all available versions in a round robin fashion.

The initial goal of this task is to apply rules that route all traffic to v1 (version 1) of the microservices. Later, you will apply a rule to route traffic based on the value of an HTTP request header.

Route to version 1

To route to one version only, you configure route rules that send traffic to default versions for the microservices.

If you haven’t already, follow the instructions in define the service versions.

  1. Run the following command to create the route rules:

Istio uses virtual services to define route rules. Run the following command to apply virtual services that will route all traffic to v1 of each microservice:

Zip

  1. $ kubectl apply -f @samples/bookinfo/networking/virtual-service-all-v1.yaml@

Because configuration propagation is eventually consistent, wait a few seconds for the virtual services to take effect.

  1. $ kubectl apply -f - <<EOF
  2. apiVersion: gateway.networking.k8s.io/v1beta1
  3. kind: HTTPRoute
  4. metadata:
  5.   name: reviews
  6. spec:
  7.   parentRefs:
  8.   - group: ""
  9.     kind: Service
  10.     name: reviews
  11.     port: 9080
  12.   rules:
  13.   - backendRefs:
  14.     - name: reviews-v1
  15.       port: 9080
  16. EOF
  1. Display the defined routes with the following command:
  1. $ kubectl get virtualservices -o yaml
  2. - apiVersion: networking.istio.io/v1beta1
  3.   kind: VirtualService
  4.   ...
  5.   spec:
  6.     hosts:
  7.     - details
  8.     http:
  9.     - route:
  10.       - destination:
  11.           host: details
  12.           subset: v1
  13. - apiVersion: networking.istio.io/v1beta1
  14.   kind: VirtualService
  15.   ...
  16.   spec:
  17.     hosts:
  18.     - productpage
  19.     http:
  20.     - route:
  21.       - destination:
  22.           host: productpage
  23.           subset: v1
  24. - apiVersion: networking.istio.io/v1beta1
  25.   kind: VirtualService
  26.   ...
  27.   spec:
  28.     hosts:
  29.     - ratings
  30.     http:
  31.     - route:
  32.       - destination:
  33.           host: ratings
  34.           subset: v1
  35. - apiVersion: networking.istio.io/v1beta1
  36.   kind: VirtualService
  37.   ...
  38.   spec:
  39.     hosts:
  40.     - reviews
  41.     http:
  42.     - route:
  43.       - destination:
  44.           host: reviews
  45.           subset: v1

You can also display the corresponding subset definitions with the following command:

  1. $ kubectl get destinationrules -o yaml
  1. $ kubectl get httproute reviews -o yaml
  2. ...
  3. spec:
  4.   parentRefs:
  5.   - group: gateway.networking.k8s.io
  6.     kind: Service
  7.     name: reviews
  8.     port: 9080
  9.   rules:
  10.   - backendRefs:
  11.     - group: ""
  12.       kind: Service
  13.       name: reviews-v1
  14.       port: 9080
  15.       weight: 1
  16.     matches:
  17.     - path:
  18.         type: PathPrefix
  19.         value: /
  20. status:
  21.   parents:
  22.   - conditions:
  23.     - lastTransitionTime: "2022-11-08T19:56:19Z"
  24.       message: Route was valid
  25.       observedGeneration: 8
  26.       reason: Accepted
  27.       status: "True"
  28.       type: Accepted
  29.     - lastTransitionTime: "2022-11-08T19:56:19Z"
  30.       message: All references resolved
  31.       observedGeneration: 8
  32.       reason: ResolvedRefs
  33.       status: "True"
  34.       type: ResolvedRefs
  35.     controllerName: istio.io/gateway-controller
  36.     parentRef:
  37.       group: gateway.networking.k8s.io
  38.       kind: Service
  39.       name: reviews
  40.       port: 9080

In the resource status, make sure that the Accepted condition is True for the reviews parent.

You have configured Istio to route to the v1 version of the Bookinfo microservices, most importantly the reviews service version 1.

Test the new routing configuration

You can easily test the new configuration by once again refreshing the /productpage of the Bookinfo app in your browser. Notice that the reviews part of the page displays with no rating stars, no matter how many times you refresh. This is because you configured Istio to route all traffic for the reviews service to the version reviews:v1 and this version of the service does not access the star ratings service.

You have successfully accomplished the first part of this task: route traffic to one version of a service.

Route based on user identity

Next, you will change the route configuration so that all traffic from a specific user is routed to a specific service version. In this case, all traffic from a user named Jason will be routed to the service reviews:v2.

This example is enabled by the fact that the productpage service adds a custom end-user header to all outbound HTTP requests to the reviews service.

Istio also supports routing based on strongly authenticated JWT on ingress gateway, refer to the JWT claim based routing for more details.

Remember, reviews:v2 is the version that includes the star ratings feature.

  1. Run the following command to enable user-based routing:

Zip

  1. $ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-test-v2.yaml@

You can confirm the rule is created using the following command:

  1. $ kubectl get virtualservice reviews -o yaml
  2. apiVersion: networking.istio.io/v1beta1
  3. kind: VirtualService
  4. ...
  5. spec:
  6.   hosts:
  7.   - reviews
  8.   http:
  9.   - match:
  10.     - headers:
  11.         end-user:
  12.           exact: jason
  13.     route:
  14.     - destination:
  15.         host: reviews
  16.         subset: v2
  17.   - route:
  18.     - destination:
  19.         host: reviews
  20.         subset: v1
  1. $ kubectl apply -f - <<EOF
  2. apiVersion: gateway.networking.k8s.io/v1beta1
  3. kind: HTTPRoute
  4. metadata:
  5.   name: reviews
  6. spec:
  7.   parentRefs:
  8.   - group: ""
  9.     kind: Service
  10.     name: reviews
  11.     port: 9080
  12.   rules:
  13.   - matches:
  14.     - headers:
  15.       - name: end-user
  16.         value: jason
  17.     backendRefs:
  18.     - name: reviews-v2
  19.       port: 9080
  20.   - backendRefs:
  21.     - name: reviews-v1
  22.       port: 9080
  23. EOF

  1. On the /productpage of the Bookinfo app, log in as user jason.

    Refresh the browser. What do you see? The star ratings appear next to each review.

  2. Log in as another user (pick any name you wish).

    Refresh the browser. Now the stars are gone. This is because traffic is routed to reviews:v1 for all users except Jason.

You have successfully configured Istio to route traffic based on user identity.

Understanding what happened

In this task, you used Istio to send 100% of the traffic to the v1 version of each of the Bookinfo services. You then set a rule to selectively send traffic to version v2 of the reviews service based on a custom end-user header added to the request by the productpage service.

Note that Kubernetes services, like the Bookinfo ones used in this task, must adhere to certain restrictions to take advantage of Istio’s L7 routing features. Refer to the Requirements for Pods and Services for details.

In the traffic shifting task, you will follow the same basic pattern you learned here to configure route rules to gradually send traffic from one version of a service to another.

Cleanup

  1. Remove the application route rules:

Zip

  1. $ kubectl delete -f @samples/bookinfo/networking/virtual-service-all-v1.yaml@
  1. $ kubectl delete httproute reviews
  1. If you are not planning to explore any follow-on tasks, refer to the Bookinfo cleanup instructions to shutdown the application.