Istio Routing Mission

Purpose

Showcases Istio’s dynamic routing capabilities with a minimal set of example applications.

Prerequisites

1. Openshift 3.10 cluster

2. Istio 1.0.x installed on the aforementioned cluster using the Istio Operator.

   1. Follow these instructions for more information about the Operator

3. Login to the cluster with the admin user

Environment preparation

Create a new project/namespace on the cluster. This is where your application will be deployed.

oc new-project <whatever valid project name you want>

In OpenShift each service account must be granted permissions with the anyuid and privileged Security Context Constraints (SCC) to enable the sidecars to run correctly.

oc adm policy add-scc-to-user anyuid -z default -n <whatever valid project name you want>
oc adm policy add-scc-to-user privileged -z default -n <whatever valid project name you want>

Build and deploy the application

With Fabric8 Maven Plugin (FMP)

Execute the following command to build the project and deploy it to OpenShift:

mvn clean fabric8:deploy -Popenshift

Configuration for FMP may be found both in pom.xml and src/main/fabric8 files/folders.

This configuration is used to define service names and deployments that control how pods are labeled/versioned on the OpenShift cluster. Labels and versions are key concepts for creating load-balanced or multi-versioned pods in a service.

With Source to Image build (S2I)

Run the following commands to apply and execute the OpenShift templates that will configure and deploy the applications:

find . | grep openshiftio | grep application | xargs -n 1 oc apply -f

oc new-app --template=istio-routing-example-client -p SOURCE_REPOSITORY_URL=https://github.com/snowdrop/istio-routing-example -p SOURCE_REPOSITORY_REF=master -p SOURCE_REPOSITORY_DIR=spring-boot-istio-routing-client
oc new-app --template=istio-routing-example-service-a -p SOURCE_REPOSITORY_URL=https://github.com/snowdrop/istio-routing-example -p SOURCE_REPOSITORY_REF=master -p SOURCE_REPOSITORY_DIR=spring-boot-istio-routing-service-a
oc new-app --template=istio-routing-example-service-b -p SOURCE_REPOSITORY_URL=https://github.com/snowdrop/istio-routing-example -p SOURCE_REPOSITORY_REF=master -p SOURCE_REPOSITORY_DIR=spring-boot-istio-routing-service-b

Use Cases

Access the application via the Istio ingress-gateway

1. Create a Gateway to forward traffic to the demo application.

   This is only necessary if your application accepts traffic at a different port/url than the default. In this case, our application accepts traffic at /, but we will access it with the path /example.

   oc apply -f rules/client-gateway-rule.yml -n $(oc project -q)

2. Access the application

   Run the following command to determine the appropriate URL to access our demo. Make sure you access the url with the HTTP scheme. HTTPS is NOT enabled by default:

   echo http://$(oc get route istio-ingressgateway -o jsonpath='{.spec.host}{"\n"}' -n istio-system)/example/

   The result of the above command is the istio-system istio-ingressgateway URL, appended with the Gateway path we defined above. Open this URL in your a web browser.

Transfer load between two versions of an application/service

1. Access the application as described in the previous use case

   1. Click "Invoke Service" in the client UI (Do this several times.)

   2. Notice that the services are load-balanced at exactly 50%, which is the default cluster behavior.

2. Configure a VirtualService to enable weight-based version routing (load-balancing) Sometimes it is important to slowly direct traffic to a new service over time, or use alternate weighting. In this case, we will supply an Istio VirtualService to control load balancing behavior.

   Run the following command:

   oc apply -f rules/load-balancing-rule.yml

   The VirtualService defined in the file above uses labels "a" and "b" to identify each unique version of the service. If multiple services match any of these labels, traffic will be divided between them accordingly. Additional routes/weights can be supplied using additional labels/service versions as desired.

3. Click "Invoke Service" in the client UI

   Do this several times. You will notice that traffic is no longer routed at 50/50%, and more traffic is directed to service version B than service version A. Adjust the weights in the rule-file and re-run the command above. You should see traffic adjust accordingly.

   Note	It could take several seconds for the VirtualService to be detected and applied by Istio.

Congratulations! You now know how to direct traffic between different versions of a service using Istio VirtualService.

Undeploy the application

With Fabric8 Maven Plugin (FMP)

mvn fabric8:undeploy

With Source to Image build (S2I)

oc delete all --all
oc delete ingress --all
find . | grep openshiftio | grep application | xargs -n 1 oc delete -f

Remove the namespace

This will delete the project from the OpenShift cluster

oc delete project <your project name>

Integration tests

To run integration tests, create a new namespace and run maven job

oc new-project <project-name>
mvn clean verify -Popenshift,openshift-it