Additional route settings
Configure additional route table settings, such as setting a default destination or weighted routing to version subsets.
When you forward requests to a Kubernetes service, virtual destination, or external service, you can configure additional settings in your route table. Review the following sections to set a default destination, route to an application subset, or assign weights to app instances.
Set a default destination
Set a default destination in a route table so that multiple routes can be easily assigned to that destination.
For example, you might want to designate multiple routes for one destination, for the purpose of assigning certain policies to certain routes. Instead of typing out the same destination definition in each of the routes, you can instead define the destination as the default, and leave the forwardTo
directive in each route empty. Note that any routes in the route table that do not specify a destination will forward traffic to the default destination.
In this example route table, the information for the ratings
destination is defined in the spec.defaultDestination
field, rather than repeated in each http
route. This way, the two routes can automatically reference the ratings definition.
apiVersion: networking.gloo.solo.io/v2
kind: RouteTable
metadata:
name: example
namespace: bookinfo
spec:
defaultDestination:
port:
number: 9080
ref:
name: ratings
namespace: bookinfo
cluster: ${REMOTE_CLUSTER1}
hosts:
- 'ratings.bookinfo.svc.cluster.local'
http:
- forwardTo: {}
labels:
"no": auth
matchers:
- headers:
- name: noauth
value: "true"
name: ratings-no-auth
- forwardTo: {}
labels:
route: ratings
name: ratings
Weighted routing to an application subset
If you are testing multiple versions of your app within your mesh, you can route to each version by using the version numbers. Additionally, you can optionally assign weights to each version of the app to determine the load or requests that each version receives.
Review the following examples:
- HTTP example for a weighted subsets that send traffic to two versions.
- TCP example for splitting TCP traffic to different httpbin and hello world apps on the same host.
HTTP example
Say that your app deployment for each version contains the app: myapp
label, and labels such as version: v1
and version: v2
. In the route table, you add references to the both versions of the app, and specify the version labels in the subset
field of each reference section.
Additionally, this example route table specifies an optional weight
for each version of the app. 75% of traffic requests to the /myapp
are directed to v1
, and 25% of traffic requests are directed to v2
. Weighted routing can be useful in scenarios such as controlled rollouts to slowly move traffic from an older to a newer version of your app.
The following example route table is provided for quick reference. For an extended example on weighted subset routing, check out the Online Boutique app example in the Solo Communities of Practice repo.
apiVersion: networking.gloo.solo.io/v2
kind: RouteTable
metadata:
name: myapp-routes
namespace: global
spec:
hosts:
- 'myapp.global.svc.cluster.local'
http:
# Route for the myapp service
- name: myapp
# Prefix matching
matchers:
- uri:
prefix: /myapp
# Forwarding directive
forwardTo:
destinations:
# Reference to the virtual destination that selects v1 of the myapp service
- ref:
name: myapp
kind: VIRTUAL_DESTINATION
subset:
version: v1
# 75% of request traffic to /myapp
weight: 75
# Reference to the virtual destination that selects v2 of the myapp service
- ref:
name: myapp
kind: VIRTUAL_DESTINATION
subset:
version: v2
# 25% of request traffic to /myapp
weight: 25
TCP weighted example
Use the following steps to set up weighted routing for TCP routes to your hello world app.
Before you begin, complete the prerequisite steps in the Routing guide.
Create a virtual destination resource for your destination app that receives TCP requests from the initiator app. The following virtual destination listens for requests on the
helloworld.vd
host on TCP port 9000. Then, the virtual destination forwards requests to any app with the labelapp: helloworld
on thetcp
port. Note that because virtual destinations are dynamic, the east-west gateway that handles the request routes it to the closest healthy app instance.kubectl --context ${REMOTE_CONTEXT1} apply -f - <<EOF apiVersion: networking.gloo.solo.io/v2 kind: VirtualDestination metadata: annotations: cluster.solo.io/cluster: "" name: helloworld-global namespace: helloworld spec: hosts: - helloworld.vd ports: - number: 9000 protocol: TCP targetPort: name: tcp services: - labels: app: helloworld EOF
Route requests initiated from your initiator app to your destination app by using the virtual destination hostname. The following route table listens for requests from any app with the label
app: productpage
on thehttpbin.httpbin.svc.cluster.local
host. Then, it forwards the request to thehelloworld-global
virtual destination that you created in the previous step. By using weighted subsets, the route table splits the traffic evenly between the v1 app on cluster 1 and v3 app on cluster 3.kubectl --context ${REMOTE_CONTEXT1} apply -f - <<EOF apiVersion: networking.gloo.solo.io/v2 kind: RouteTable metadata: annotations: cluster.solo.io/cluster: "" name: bookinfo namespace: bookinfo spec: hosts: - httpbin.httpbin.svc.cluster.local tcp: - forwardTo: destinations: - kind: VIRTUAL_DESTINATION port: number: 9000 ref: name: helloworld-global namespace: helloworld subset: version: v1 weight: 50 - kind: VIRTUAL_DESTINATION port: number: 9000 ref: name: helloworld-global namespace: helloworld subset: version: v3 weight: 50 matchers: - port: 9000 workloadSelectors: - selector: labels: app: productpage EOF
Test the TCP routes from the initiator app to your destination app.
- Log into the product page app.
kubectl -n bookinfo exec -it deploy/productpage-v1 -c netcat --context $REMOTE_CONTEXT1 -- sh
- Use the
netcat
command to test the connection to the hello world app along the TCP route on port 9000.echo "Hello" | nc -v httpbin.httpbin.svc.cluster.local 9000
- In the response, check that the connection request succeeds and you get a message from either hello-v1 in cluster 1 or hello-v3 in cluster 2.
Connection to httpbin.httpbin.svc.cluster.local 9000 port [tcp/*] succeeded! hello-v1 Hello
- Close the connection by entering
control+c
and repeat the previous command a couple times until you see a response from the other hello app.Connection to httpbin.httpbin.svc.cluster.local 9000 port [tcp/*] succeeded! hello-v3 Hello
- To log out of the pod, close the connection by entering
control+c
and then enterexit
.
- Log into the product page app.
Optional: Clean up the resources that you created.
kubectl delete -n helloworld vd helloworld-global --context $REMOTE_CONTEXT1 kubectl delete -n bookinfo rt bookinfo --context $REMOTE_CONTEXT1
Route table annotations for Istio virtual services
You can add annotations to the route table that are populated to the Istio virtual service that the route table is translated to. A common example is to add annotations to exclude the virtual service from being managed by ExternalDNS, such as in cases where you want to manually manage the DNS record or integrate it with a different DNS provider.
Keep in mind the following rules when adding annotations to a virtual service via route tables:
- Annotations that are automatically set by Gloo Mesh Enterprise, such as
cluster.solo.io/cluster
cannot be overwritten. If you specify an annotation that is set by Gloo Mesh Enterprise, the annotation is ignored. - Annotation keys must be unique. You cannot add multiple annotations with the same key, but different values, such as
external-dns.alpha.kubernetes.io/exclude: "true"
andexternal-dns.alpha.kubernetes.io/exclude: "false"
. If you add multiple annotations with the same key to the route table, the Kubernetes API server randomly selects one of the keys and creates the route table with that key-value pair. All other duplicate keys are ignored. Because of that, the corresponding virtual service is created with the same key-value pair that was added to the route table. - If you have a delegated route table setup, annotations can be added only to parent route tables. When you add the annotation to a child or grandchild route table, the annotation is ignored and a warning is added to the status of the child or grandchild route table.
To add annotations via a route table:
Create a route table with the
cluster.solo.io/cluster: mycluster
annotation to verify that you cannot create a conflicting annotation. This annotation is automatically added by Gloo Mesh Enterprise when the route table is translated into an Istio virtual service. Although you can create the route table, the annotation is not added to the translated virtual service.kubectl apply -f- <<EOF apiVersion: networking.gloo.solo.io/v2 kind: RouteTable metadata: name: annotations namespace: bookinfo spec: hosts: - annotations.com # Selects the virtual gateway you previously created virtualGateways: - name: istio-ingressgateway namespace: bookinfo virtualServiceAnnotations: cluster.solo.io/cluster: mycluster http: # Route for the main productpage app - name: productpage matchers: - uri: prefix: /productpage forwardTo: destinations: - ref: name: productpage namespace: bookinfo port: number: 9080 EOF
Get the details of the route table and verify that you see a warning about the existing cluster annotation.
kubectl get routetable annotations -n bookinfo -o yaml
Example output:
status: common: State: approval: WARNING message: '[1 WARNINGS]: skipping virtualServiceAnnotations with key cluster.solo.io/cluster since an annotation with this key is already present in the VirtualService metadata ' observedGeneration: 1 workspaceConditions: WARNING: 1
Verify that the annotation is not added to the Istio virtual service.
Get the name of the virtual service.
kubectl get virtualservices -n gloo-mesh-gateways | grep routetable-annotations
Get the details of the virtual service.
kubectl get virtualservice <name> -n gloo-mesh-gateways -o yaml
Modify the route table and add other annotations. For example, you can add an annotation to exclude a service from being managed by ExternalDNS as shown in the following example. This setup can be useful if you want to manually manage the DNS record for the ingress gateway, or integrate and manage it via a different DNS provider.
kubectl apply -f- <<EOF apiVersion: networking.gloo.solo.io/v2 kind: RouteTable metadata: name: annotations namespace: bookinfo spec: hosts: - annotations.com # Selects the virtual gateway you previously created virtualGateways: - name: istio-ingressgateway namespace: bookinfo virtualServiceAnnotations: external-dns.alpha.kubernetes.io/exclude: "true" external-dns.alpha.kubernetes.io/ttl: "60" http: # Route for the main productpage app - name: productpage matchers: - uri: prefix: /productpage forwardTo: destinations: - ref: name: productpage namespace: bookinfo port: number: 9080 EOF
Get the details of the route table and verify that it shows a status of
ACCEPTED
.kubectl get routetable annotations -n bookinfo -o yaml
Verify that the annotations are added to the virtual service.
kubectl get virtualservice <name> -n gloo-mesh-gateways -o yaml
Example output:
apiVersion: networking.istio.io/v1 kind: VirtualService metadata: annotations: cluster.solo.io/cluster: gloo-gateway-docs-mgt external-dns.alpha.kubernetes.io/exclude: "true" external-dns.alpha.kubernetes.io/ttl: "60" ...
Optional: Clean up the resources that you created in this guide.
kubectl delete routetable annotations -n bookinfo