[enterprise-4.4] Routing

_topic_map.yml

@@ -1406,6 +1406,11 @@ Topics:
     File: ossm-tutorial-jaeger-tracing
   - Name: Automatic route creation
     File: ossm-auto-route
+- Name: Service mesh user guide
+  Dir: service_mesh_user_guide
+  Topics:
+  - Name: Traffic management
+    File: ossm-traffic-manage
 #  - Name: Grafana tutorial
 #    File: ossm-tutorial-grafana
 #  - Name: Prometheus tutorial

modules/ossm-routing-bookinfo-example.adoc

@@ -0,0 +1,158 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_user_guide/ossm-traffic-manage.adoc
+
+[id="ossm-routing-bookinfo_{context}"]
+= Routing example using the bookinfo application
+
+The {ProductShortName} Bookinfo sample application consists of four separate microservices, each with multiple versions. Three different versions, one of the microservices called `reviews`, have been deployed and are running concurrently.
+
+.Prerequisites:
+
+* Deploy the Bookinfo sample application to work with the following examples.
+
+.About this task
+
+To illustrate the problem this causes, access the bookinfo app `/product page` in a browser and refresh several times.
+
+Sometimes the book review output contains star ratings and other times it does not. Without an explicit default service version to route to, {ProductShortName} routes requests to all available versions one after the other.
+
+This tutorial helps you apply rules that route all traffic to `v1` (version 1) of the microservices. Later, you can apply a rule to route traffic based on the value of an HTTP request header.
+
+[id="ossm-routing-bookinfo-applying_{context}"]
+== Applying a virtual service
+
+To route to one version only, apply virtual services that set the default version for the micro-services. In the following example, the virtual service routes all traffic to `v1` of each micro-service
+
+1.  Run the following command to apply the virtual services:
+
+    $ oc apply -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/virtual-service-all-v1.yaml
++
+1. To test the command was successful, display the defined routes with the following command:
++
+    $ oc get virtualservices -o yaml
++    
+That command returns the following YAML file. 
++
+[source,yaml]
+----
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: details
+  ...
+spec:
+  hosts:
+  - details
+  http:
+  - route:
+    - destination:
+      host: details
+      subset: v1
+---
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: productpage
+  ...
+spec:
+  gateways:
+  - bookinfo-gateway
+  - mesh
+  hosts:
+  - productpage
+  http:
+  - route:
+    - destination:
+      host: productpage
+      subset: v1
+---
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: ratings
+  ...
+spec:
+  hosts:
+  - ratings
+  http:
+  - route:
+    - destination:
+      host: ratings
+      subset: v1
+---
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: reviews
+  ...
+spec:
+  hosts:
+  - reviews
+  http:
+  - route:
+    - destination:
+      host: reviews
+      subset: v1
+----
++
+You have configured {ProductShortName} to route to the `v1` version of the Bookinfo microservices, most importantly the `reviews` service version 1.
+
+[id="ossm-routing-bookinfo-test_{context}"]
+== Test the new routing configuration
+
+You can easily test the new configuration by once again refreshing the `/productpage` of the Bookinfo app.
+
+1.  Open the Bookinfo site in your browser. The URL is `http://$GATEWAY_URL/productpage`, where `$GATEWAY_URL` is the External IP address of the ingress.
++
+The reviews part of the page displays with no rating stars, no matter how many times you refresh. This is because you configured {ProductShortName} 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.
++
+Your service mesh now routes traffic to one version of a service.
+
+[id="ossm-routing-bookinfo-route_{context}"]
+== Route based on user identity
+
+Next, 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`.
+
+Note that {ProductShortName} doesn't have any special, built-in understanding of user identity. 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.
+
+1. Run the following command to enable user-based routing:
+
+    $ oc apply -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/virtual-service-reviews-test-v2.yaml
++
+1. Confirm the rule is created:
++
+    $ oc get virtualservice reviews -o yaml
++    
+That command returns the following YAML file. 
++
+[source,yaml]
+----
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: reviews
+  ...
+spec:
+  hosts:
+  - reviews
+  http:
+  - match:
+    - headers:
+      end-user:
+        exact: jason
+    route:
+    - destination:
+      host: reviews
+      subset: v2
+  - route:
+    - destination:
+      host: reviews
+      subset: v1
+----
++
+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.
++
+1. 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 {ProductShortName} to route traffic based on user identity.

modules/ossm-routing-ingress.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_user_guide/ossm-traffic-manage.adoc
+
+[id="ossm-routing-ingress_{context}"]
+= Managing ingress traffic
+
+In {ProductName}, the Ingress Gateway enables Service Mesh features such as monitoring, security, and route rules to be applied to traffic entering the cluster. Configure {ProductShortName} to expose a service outside of the service mesh using an {ProductShortName} gateway.
+
+[id="ossm-routing-determine-ingress_{context}"]
+== Determining the ingress IP and ports
+
+Run the following command to determine if your Kubernetes cluster is running in an environment that supports external load balancers:
+
+----
+$ oc get svc istio-ingressgateway -n istio-system
+----
+
+That command returns the `NAME`, `TYPE`, `CLUSTER-IP`, `EXTERNAL-IP`,    `PORT(S)`, and `AGE` of each item in your namespace. 
+
+If the `EXTERNAL-IP` value is set, your environment has an external load balancer that you can use for the ingress gateway. 
+
+If the `EXTERNAL-IP` value is `<none>`, or perpetually `<pending>`, your environment does not provide an external load balancer for the ingress gateway. You can access the gateway using the service's https://kubernetes.io/docs/concepts/services-networking/service/#nodeport[node port].
+
+Choose the instructions for your environment:
+
+.Configuring routing with a load balancer
+
+Follow these instructions if your environment has an external load balancer.
+
+Set the ingress IP and ports:
+
+----
+$ export INGRESS_HOST=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
+----
+
+----
+$ export INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].port}')
+----
+
+----
+$ export SECURE_INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].port}')
+----
+
+In some environments, the load balancer may be exposed using a host name instead of an IP address. For that case, the ingress gateway's `EXTERNAL-IP` value is not be an IP address. Instead, it's a host name, and the previous command fails to set the `INGRESS_HOST` environment variable.
+
+Use the following command to correct the `INGRESS_HOST` value:
+
+----
+$ export INGRESS_HOST=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
+----
+
+.Configuring routing without a load balancer
+
+Follow these instructions if your environment does not have an external load balancer. You must use a node port instead.
+
+Set the ingress ports:
+
+----
+$ export INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].nodePort}')
+----
+
+----
+$ export SECURE_INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].nodePort}')
+----