Getting started with OpenShift Service Mesh

This tutorial explains how to use the OpenShift Service Mesh to manage the bookinfo demo application.


To follow this guide, please make sure that you have the following tools installed:


You can download the OpenShift command directly from OpenShift Web Console. Open the help menu (marked as a question mark at the top right) and select the "Command line tools" entry.

Step 1: Creating the ServiceMeshControlPlane

The ServiceMeshControlPlane manages all services that are part of a service mesh. Creating multiple control planes allows for creating multiple independent service meshes, for example in a multi-tenancy environment.

  1. Create a new namespace called demo-ossm-controlplane

    oc new-project demo-ossm-controlplane

    If you get an error that the namespace already exists, please pick another name and try again. We recommend prefixing the name with the name of your organization to minimize potential for name collisions.

  2. Create a ServiceMeshControlPlane

    oc create -n demo-ossm-controlplane -f - <<EOF
    kind: ServiceMeshControlPlane
      name: basic
      version: v2.3
        type: Jaeger
        sampling: 10000
          name: jaeger
              type: Memory
          enabled: true
          name: kiali
          enabled: true
  3. Watch the progress of the control plane deployment

    oc get pods -n demo-ossm-controlplane -w
  4. Verify the control plane is ready

    oc get smcp -n demo-ossm-controlplane

    You should see your new ServiceMeshControlPlane with status ComponentsReady.

Step 2: Creating the Service Mesh member roll

The ServiceMeshMemberRoll associates OpenShift projects with ServiceMeshControlPlanes. Each project can belong to only one Control Plane, but one Control Plane can manage multiple projects. The ServiceMeshControlPlane can only manage services in projects that are associated with it via a ServiceMeshMemberRoll.

  1. Create a new project to contain the application that shall be part of the service mesh

    oc new-project demo-ossm-bookinfo
  2. Create a ServiceMeshMemberRoll in the control plane namespace to associate this new project with the control plane

    oc create -n demo-ossm-controlplane -f - <<EOF
    kind: ServiceMeshMemberRoll
      name: default
        - demo-ossm-bookinfo
  3. Verify the ServiceMeshMemberRoll was successfully created

    oc get smmr -n demo-ossm-controlplane default

    A status of Configured indicates that installation was successful.

Step 3: Deploying the bookinfo demo application

bookinfo is a small sample application which is built from microservices. It displays information about a book. The main productpage service calls other microservices to collect information and reviews pertaining to a book.

  1. Deploy the Bookinfo application from its manifest:

    oc apply -n demo-ossm-bookinfo -f
  2. Deploy the ingress gateway, which allows public access to the application

    oc apply -n demo-ossm-bookinfo -f
  3. Deploy the destination rules for the application, which configure the routing between the individual microservices

    oc apply -n demo-ossm-bookinfo -f
  4. Verify all pods are ready

    oc get pods -n demo-ossm-bookinfo

Step 4: Enable sidecar injection

To avoid interference between different operators, the OpenShift Service Mesh controller refuses to touch any deployments that aren’t annotated a certain way. We need to add this annotation to all our deployments to allow the controller to inject the necessary sidecars.

  1. Check all the deployments of our application

    oc get deployment -n demo-ossm-bookinfo
  2. Add the annotation to all deployments

    oc get deployment -n demo-ossm-bookinfo -o NAME | while read line ; do oc annotate "$line" -n demo-ossm-bookinfo "" ; done

    The bookinfo application technically already has sidecar injection enabled by default. However, the step is highlighted here anyways, since it’s necessary on any custom workloads.

  3. View the bookinfo application in your browser

    Run the following to get the application URL:

    export GATEWAY_URL=$(oc -n demo-ossm-controlplane get route istio-ingressgateway -o jsonpath='{}')
    echo "http://$GATEWAY_URL/productpage"
  4. You can use the following command to generate some traffic to your application for testing:

    while true ; do curl "http://$GATEWAY_URL/productpage" > /dev/null ; sleep 1 ; done

Step 5: Explore your microservices using the tools provided by OpenShift Service Mesh

  1. Navigate to kiali

    1. Find the URL using this command:

      oc -n demo-ossm-controlplane get route kiali -o jsonpath='{}'
    2. Click on "Log In with OpenShift" to log into Kiali

    3. Navigate to Graph to see an overview of your service mesh.

    4. For more information on Kiali and its features, see the Kiali documentation.

  2. Navigate to Jaeger

    1. Find the URL using this command:

      oc -n demo-ossm-controlplane get route jaeger -o jsonpath='{}'
    2. Click on "Log In with OpenShift" to log into Jaeger

    3. Select a service in the drop-down (such as the productpage service) and click on Find Traces to query for your service’s traces

    4. For more information on Jaeger and its features, see the Jaeger documentation.

Step 6: Cleanup

Once you no longer need your demo deployment of the bookinfo application and its ServiceMeshControlPlane, clean it up by deleting the corresponding projects:

oc delete project demo-ossm-bookinfo
oc delete project demo-ossm-controlplane