snowdrop / istio-distributed-tracing-example

A booster demonstrating Istio Distributed Tracing functionality

Istio Distributed Tracing Mission

Table of Contents

• Purpose
• Prerequisites
• Environment preparation
• Build and deploy the application
  • With Dekorate:
• Use Cases
  • Access the application via the Istio ingress-gateway
  • View application traces
  • Undeploy the application
• Integration tests
  • Remove Jaeger UI security
  • Execute the Integration Tests

Purpose

Showcase Istio’s Distributed Tracing via a (minimally) instrumented set of Spring Boot applications

Prerequisites

1. JDK 11+ installed with JAVA_HOME configured appropriately

2. Openshift 4.12 cluster

3. Istio installed on the aforementioned cluster using the Red Hat OpenShift Service Mesh Operator.

4. 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>

Add the <whatever valid project name you want> project to the Istio member roll. More information in this link.

Build and deploy the application

With Dekorate:

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

mvn clean verify -Popenshift -Ddekorate.deploy=true

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.

Use Cases

Access the application via the Istio ingress-gateway

1. Create a RouteRule to forward traffic from istio-ingress to the demo application

   oc create -f rules/greeting-gateway.yml

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)/greeting/

   The result of the above command is the istio-system istio-ingress URL, appended with the RouteRule path. Open this URL in your a web browser.

3. Follow the instructions in the application UI

View application traces

1. Access the Jaeger tracing dashboard

   The traces from the invocation of the two endpoints should look like the following:

   

   Note that it could take a few seconds for all the spans to be collected and presented in a trace that matches the picture above

Undeploy the application

Remove the namespace

This will delete the project from the OpenShift cluster

oc delete project <your project name>

Integration tests

To run integration tests, first follow the steps on the Environment preparation section to create and prepare a new namespace.

Remove Jaeger UI security

Caution

For the integration tests to work it is required that the Jaeger UI isn’t secured by authentication, as it is in the default configuration.

Warning

Disabling security isn’t the suggested configuration but it is required for the integration tests to work.

By default, when installing the Red Hat OpenShift distributed tracing platform operator, it will install a Jaeger instance with the security enabled:

Secured Jaeger UI configuration

  ingress:
    enabled: true
    openshift:
      htpasswdFile: /etc/proxy/htpasswd/auth
      sar: '{"namespace": "istio-system", "resource": "pods", "verb": "get"}'
    options: {}
    resources: {}
    security: oauth-proxy

Disabling security is accomplished by setting the spec.ingress.security on the Jaeger operator to none.

This can be done either by using the OpenShift console (Installed operators > Red Hat OpenShift distributed tracing platform > Jaguer > Edit Jaeger) or using the CLI.

Note	More information on the Jaeger configuration at the Jaeger configuration reference page.

To disable security execute the following CLI commands.

Set the istio-system as the default project

oc project istio-system

Patch jaeger to disable console security

oc patch jaeger jaeger --patch '{"spec":{"ingress":{"security": "none" }}}' --type=merge

The result should be:

jaeger.jaegertracing.io/jaeger patched

Which will result in the following configuration.

Unsecured Jaeger UI configuration

  ingress:
    enabled: true
    options: {}
    resources: {}
    security: none

Execute the Integration Tests

After everything is set up, move back to the project where this example will be installed.

oc project <whatever valid project name you want>

Then run the following commands.

Commands to execute the integration tests

mvn clean verify -pl spring-boot-istio-distributed-tracing-cute-name-service -Popenshift -Ddekorate.deploy=true
mvn clean verify -pl spring-boot-istio-distributed-tracing-greeting-service -Popenshift -Ddekorate.deploy=true
oc create -f rules/greeting-gateway.yml
mvn clean verify -pl tests -Popenshift-it