Skip to content

Commit d9b50df

Browse files
JSticklerJStickler
authored
Merge pull request #19867 from neal-timpe/routing
Routing
2 parents 0136e43 + 5485871 commit d9b50df

File tree

5 files changed

+530
-0
lines changed

5 files changed

+530
-0
lines changed

‎_topic_map.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1420,6 +1420,11 @@ Topics:
14201420
File: ossm-tutorial-jaeger-tracing
14211421
- Name: Automatic route creation
14221422
File: ossm-auto-route
1423+
- Name: Service mesh user guide
1424+
Dir: service_mesh_user_guide
1425+
Topics:
1426+
- Name: Traffic management
1427+
File: ossm-traffic-manage
14231428
# - Name: Grafana tutorial
14241429
# File: ossm-tutorial-grafana
14251430
# - Name: Prometheus tutorial

‎modules/ossm-routing-bookinfo-example.adoc‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/service_mesh_user_guide/ossm-traffic-manage.adoc
4+
5+
[id="ossm-routing-bookinfo_{context}"]
6+
= Routing example using the bookinfo application
7+
8+
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.
9+
10+
.Prerequisites:
11+
12+
* Deploy the Bookinfo sample application to work with the following examples.
13+
14+
.About this task
15+
16+
To illustrate the problem this causes, access the bookinfo app `/product page` in a browser and refresh several times.
17+
18+
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.
19+
20+
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.
21+
22+
[id="ossm-routing-bookinfo-applying_{context}"]
23+
== Applying a virtual service
24+
25+
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
26+
27+
1. Run the following command to apply the virtual services:
28+
29+
$ oc apply -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/virtual-service-all-v1.yaml
30+
+
31+
1. To test the command was successful, display the defined routes with the following command:
32+
+
33+
$ oc get virtualservices -o yaml
34+
+
35+
That command returns the following YAML file.
36+
+
37+
[source,yaml]
38+
----
39+
apiVersion: networking.istio.io/v1alpha3
40+
kind: VirtualService
41+
metadata:
42+
name: details
43+
...
44+
spec:
45+
hosts:
46+
- details
47+
http:
48+
- route:
49+
- destination:
50+
host: details
51+
subset: v1
52+
---
53+
apiVersion: networking.istio.io/v1alpha3
54+
kind: VirtualService
55+
metadata:
56+
name: productpage
57+
...
58+
spec:
59+
gateways:
60+
- bookinfo-gateway
61+
- mesh
62+
hosts:
63+
- productpage
64+
http:
65+
- route:
66+
- destination:
67+
host: productpage
68+
subset: v1
69+
---
70+
apiVersion: networking.istio.io/v1alpha3
71+
kind: VirtualService
72+
metadata:
73+
name: ratings
74+
...
75+
spec:
76+
hosts:
77+
- ratings
78+
http:
79+
- route:
80+
- destination:
81+
host: ratings
82+
subset: v1
83+
---
84+
apiVersion: networking.istio.io/v1alpha3
85+
kind: VirtualService
86+
metadata:
87+
name: reviews
88+
...
89+
spec:
90+
hosts:
91+
- reviews
92+
http:
93+
- route:
94+
- destination:
95+
host: reviews
96+
subset: v1
97+
----
98+
+
99+
You have configured {ProductShortName} to route to the `v1` version of the Bookinfo microservices, most importantly the `reviews` service version 1.
100+
101+
[id="ossm-routing-bookinfo-test_{context}"]
102+
== Test the new routing configuration
103+
104+
You can easily test the new configuration by once again refreshing the `/productpage` of the Bookinfo app.
105+
106+
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.
107+
+
108+
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.
109+
+
110+
Your service mesh now routes traffic to one version of a service.
111+
112+
[id="ossm-routing-bookinfo-route_{context}"]
113+
== Route based on user identity
114+
115+
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`.
116+
117+
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.
118+
119+
1. Run the following command to enable user-based routing:
120+
121+
$ oc apply -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/virtual-service-reviews-test-v2.yaml
122+
+
123+
1. Confirm the rule is created:
124+
+
125+
$ oc get virtualservice reviews -o yaml
126+
+
127+
That command returns the following YAML file.
128+
+
129+
[source,yaml]
130+
----
131+
apiVersion: networking.istio.io/v1alpha3
132+
kind: VirtualService
133+
metadata:
134+
name: reviews
135+
...
136+
spec:
137+
hosts:
138+
- reviews
139+
http:
140+
- match:
141+
- headers:
142+
end-user:
143+
exact: jason
144+
route:
145+
- destination:
146+
host: reviews
147+
subset: v2
148+
- route:
149+
- destination:
150+
host: reviews
151+
subset: v1
152+
----
153+
+
154+
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.
155+
+
156+
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.
157+
158+
You have successfully configured {ProductShortName} to route traffic based on user identity.

‎modules/ossm-routing-ingress.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/service_mesh_user_guide/ossm-traffic-manage.adoc
4+
5+
[id="ossm-routing-ingress_{context}"]
6+
= Managing ingress traffic
7+
8+
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.
9+
10+
[id="ossm-routing-determine-ingress_{context}"]
11+
== Determining the ingress IP and ports
12+
13+
Run the following command to determine if your Kubernetes cluster is running in an environment that supports external load balancers:
14+
15+
----
16+
$ oc get svc istio-ingressgateway -n istio-system
17+
----
18+
19+
That command returns the `NAME`, `TYPE`, `CLUSTER-IP`, `EXTERNAL-IP`, `PORT(S)`, and `AGE` of each item in your namespace.
20+
21+
If the `EXTERNAL-IP` value is set, your environment has an external load balancer that you can use for the ingress gateway.
22+
23+
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].
24+
25+
Choose the instructions for your environment:
26+
27+
.Configuring routing with a load balancer
28+
29+
Follow these instructions if your environment has an external load balancer.
30+
31+
Set the ingress IP and ports:
32+
33+
----
34+
$ export INGRESS_HOST=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
35+
----
36+
37+
----
38+
$ export INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].port}')
39+
----
40+
41+
----
42+
$ export SECURE_INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].port}')
43+
----
44+
45+
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.
46+
47+
Use the following command to correct the `INGRESS_HOST` value:
48+
49+
----
50+
$ export INGRESS_HOST=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
51+
----
52+
53+
.Configuring routing without a load balancer
54+
55+
Follow these instructions if your environment does not have an external load balancer. You must use a node port instead.
56+
57+
Set the ingress ports:
58+
59+
----
60+
$ export INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].nodePort}')
61+
----
62+
63+
----
64+
$ export SECURE_INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].nodePort}')
65+
----

0 commit comments

Comments
 (0)