When you deploy an application into the Service Mesh, there are several differences between the behavior of applications in the upstream community version of Istio and the behavior of applications within a Red Hat OpenShift Service Mesh installation.

Creating control plane templates

You can create reusable configurations with ServiceMeshControlPlane templates. Individual users can extend the templates they create with their own configurations. Templates can also inherit configuration information from other templates. For example, you can create an accounting control plane for the accounting team and a marketing control plane for the marketing team. If you create a development template and a production template, members of the marketing team and the accounting team can extend the development and production templates with team specific customization.

When you configure control plane templates, which follow the same syntax as the ServiceMeshControlPlane, users inherit settings in a hierarchical fashion. The Operator is delivered with a default template with default settings for Red Hat OpenShift Service Mesh. To add custom templates you must create a ConfigMap named smcp-templates in the openshift-operators project and mount the ConfigMap in the Operator container at /usr/local/share/istio-operator/templates.

Creating the ConfigMap

Follow this procedure to create the ConfigMap.

Prerequisites
  • An installed, verified Service Mesh Operator.

  • An account with the cluster-admin role.

  • Location of the Operator deployment.

  • Access to the OpenShift CLI (oc).

Procedure
  1. Log in to the OpenShift Container Platform CLI as a cluster administrator.

  2. From the CLI, run this command to create the ConfigMap named smcp-templates in the openshift-operators project and replace <templates-directory> with the location of the ServiceMeshControlPlane files on your local disk:

    $ oc create configmap --from-file=<templates-directory> smcp-templates -n openshift-operators
  3. Locate the Operator ClusterServiceVersion name.

    $ oc get clusterserviceversion -n openshift-operators | grep 'Service Mesh'
    Example output
    maistra.v1.0.0            Red Hat OpenShift Service Mesh   1.0.0                Succeeded
  4. Edit the Operator cluster service version to instruct the Operator to use the smcp-templates ConfigMap.

    $ oc edit clusterserviceversion -n openshift-operators maistra.v1.0.0
  5. Add a volume mount and volume to the Operator deployment.

    deployments:
      - name: istio-operator
        spec:
          template:
            spec:
              containers:
                volumeMounts:
                  - name: discovery-cache
                    mountPath: /home/istio-operator/.kube/cache/discovery
                  - name: smcp-templates
                    mountPath: /usr/local/share/istio-operator/templates/
              volumes:
                - name: discovery-cache
                  emptyDir:
                    medium: Memory
                - name: smcp-templates
                  configMap:
                    name: smcp-templates
    ...
  6. Save your changes and exit the editor.

  7. You can now use the template parameter in the ServiceMeshControlPlane to specify a template.

    apiVersion: maistra.io/v1
    kind: ServiceMeshControlPlane
    metadata:
      name: minimal-install
    spec:
      template: default

Enabling automatic sidecar injection

When deploying an application, you must opt-in to injection by setting the sidecar.istio.io/inject annotation to "true". Opting in ensures that the sidecar injection does not interfere with other OpenShift Container Platform features such as builder pods used by numerous frameworks within the OpenShift Container Platform ecosystem.

Prerequisites
  • Identify the deployments for which you want to enable automatic sidecar injection.

Procedure
  1. Open the application’s deployment configuration YAML file in an editor. To find a deployment use the oc get command. For example, for an app called sleep in the sleep namespace, use the following command to see the resource in YAML format.

    $ oc get deployment sleep -o yaml
  2. Add sidecar.istio.io/inject to the configuration YAML with a value of "true" in the spec.template.metadata.annotations.sidecar.istio/inject field. See the following example for an app called sleep.

    Sleep test application example sleep.yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      labels:
        app: sleep
      name: sleep
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: sleep
      template:
        metadata:
          annotations:
            sidecar.istio.io/inject: "true"
          labels:
            app: sleep
        spec:
          containers:
          - name: sleep
            image: curlimages/curl
            command: ["/bin/sleep","3650d"]
            imagePullPolicy: IfNotPresent
  3. Save the configuration file.

  4. Add the file back to the project that contains your app. In this example, sleep is the name of the project that contains the sleep app and sleep.yaml is the file you edited.

    $ oc apply -n sleep -f sleep.yaml
  5. To verify that the resource uploaded successfully, run the following command.

    $ oc get deployment sleep -o yaml

Setting environment variables on the proxy in applications through annotations

You can set environment variables on the sidecar proxy for applications by adding pod annotations in the deployment in the injection-template.yaml file. The environment variables are injected to the sidecar.

Example injection-template.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: resource
spec:
  replicas: 7
  selector:
    matchLabels:
      app: resource
  template:
    metadata:
      annotations:
        sidecar.maistra.io/proxyEnv: "{ \"maistra_test_env\": \"env_value\", \"maistra_test_env_2\": \"env_value_2\" }"

maistra.io/ labels and annotations should never be included in user-created resources, because they indicate that the resources are generated and managed by the Operator. If you are copying content from an Operator-generated resource when creating your own resources, do not include labels or annotations that start with maistra.io/ or your resource will be overwritten or deleted by the Operator during the next reconciliation.

Updating Mixer policy enforcement

In previous versions of Red Hat OpenShift Service Mesh, Mixer’s policy enforcement was enabled by default. Mixer policy enforcement is now disabled by default. You must enable it before running policy tasks.

Prerequisites
  • Access to the OpenShift CLI (oc).

The examples use <istio-system> as the control plane namespace. Replace this value with the namespace where you deployed the Service Mesh Control Plane (SMCP).
Procedure
  1. Log in to the OpenShift Container Platform CLI.

  2. Run this command to check the current Mixer policy enforcement status:

    $ oc get cm -n <istio-system> istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks
  3. If disablePolicyChecks: true, edit the Service Mesh ConfigMap:

    $ oc edit cm -n <istio-system> istio
  4. Locate disablePolicyChecks: true within the ConfigMap and change the value to false.

  5. Save the configuration and exit the editor.

  6. Re-check the Mixer policy enforcement status to ensure it is set to false.

Setting the correct network policy

Service Mesh creates network policies in the control plane and member namespaces to allow traffic between them. Before you deploy, consider the following conditions to ensure the services in your service mesh that were previously exposed through an OpenShift Container Platform route.

  • Traffic into the service mesh must always go through the ingress-gateway for Istio to work properly.

  • Deploy services external to the service mesh in separate namespaces that are not in any service mesh.

  • Non-mesh services that need to be deployed within a service mesh enlisted namespace should label their deployments maistra.io/expose-route: "true", which ensures OpenShift Container Platform routes to these services still work.

Bookinfo example application

The Bookinfo example application allows you to test your Red Hat OpenShift Service Mesh 2.0.8 installation on OpenShift Container Platform.

The Bookinfo application displays information about a book, similar to a single catalog entry of an online book store. The application displays a page that describes the book, book details (ISBN, number of pages, and other information), and book reviews.

The Bookinfo application consists of these microservices:

  • The productpage microservice calls the details and reviews microservices to populate the page.

  • The details microservice contains book information.

  • The reviews microservice contains book reviews. It also calls the ratings microservice.

  • The ratings microservice contains book ranking information that accompanies a book review.

There are three versions of the reviews microservice:

  • Version v1 does not call the ratings Service.

  • Version v2 calls the ratings Service and displays each rating as one to five black stars.

  • Version v3 calls the ratings Service and displays each rating as one to five red stars.

Installing the Bookinfo application

This tutorial walks you through how to create a sample application by creating a project, deploying the Bookinfo application to that project, and viewing the running application in Service Mesh.

Prerequisites:
  • OpenShift Container Platform 4.1 or higher installed.

  • Red Hat OpenShift Service Mesh 2.0.8 installed.

  • Access to the OpenShift CLI (oc).

  • An account with the cluster-admin role.

The Bookinfo sample application cannot be installed on IBM Z and IBM Power Systems.

Procedure
  1. Log in to the OpenShift Container Platform web console as a user with cluster-admin rights. If you use Red Hat OpenShift Dedicated, you must have an account with the dedicated-admin role.

  2. Click to HomeProjects.

  3. Click Create Project.

  4. Enter bookinfo as the Project Name, enter a Display Name, and enter a Description, then click Create.

    • Alternatively, you can run this command from the CLI to create the bookinfo project.

      $ oc new-project bookinfo
  5. Click OperatorsInstalled Operators.

  6. Click the Project menu and use the control plane namespace. In this example, use istio-system.

  7. Click the Red Hat OpenShift Service Mesh Operator.

  8. Click the Istio Service Mesh Member Roll tab.

    1. If you have already created a Istio Service Mesh Member Roll, click the name, then click the YAML tab to open the YAML editor.

    2. If you have not created a ServiceMeshMemberRoll, click Create ServiceMeshMemberRoll.

  9. Click Members, then enter the name of your project in the Value field.

  10. Click Create to save the updated Service Mesh Member Roll.

    1. Or, save the following example to a YAML file.

      Bookinfo ServiceMeshMemberRoll example servicemeshmemberroll-default.yaml
      apiVersion: maistra.io/v1
      kind: ServiceMeshMemberRoll
      metadata:
        name: default
      spec:
        members:
        - bookinfo
    2. Run the following command to upload that file and create the ServiceMeshMemberRoll resource in the istio-system namespace. In this example, istio-system is the name of the control plane project.

      $ oc create -n istio-system -f servicemeshmemberroll-default.yaml
  11. Run the following command to verify the ServiceMeshMemberRoll was created successfully.

    $ oc get smmr -n istio-system

    The installation has finished successfully when the STATUS column is Configured.

    NAME      READY   STATUS       AGE
    default   1/1     Configured   2m27s
  12. From the CLI, deploy the Bookinfo application in the `bookinfo` project by applying the bookinfo.yaml file:

    $ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-2.0/samples/bookinfo/platform/kube/bookinfo.yaml

    You should see output similar to the following:

    service/details created
    serviceaccount/bookinfo-details created
    deployment.apps/details-v1 created
    service/ratings created
    serviceaccount/bookinfo-ratings created
    deployment.apps/ratings-v1 created
    service/reviews created
    serviceaccount/bookinfo-reviews created
    deployment.apps/reviews-v1 created
    deployment.apps/reviews-v2 created
    deployment.apps/reviews-v3 created
    service/productpage created
    serviceaccount/bookinfo-productpage created
    deployment.apps/productpage-v1 created
  13. Create the ingress gateway by applying the bookinfo-gateway.yaml file:

    $ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-2.0/samples/bookinfo/networking/bookinfo-gateway.yaml

    You should see output similar to the following:

    gateway.networking.istio.io/bookinfo-gateway created
    virtualservice.networking.istio.io/bookinfo created
  14. Set the value for the GATEWAY_URL parameter:

    Replace <control_plane_project> with the name of your control plane project. In this example, the control plane project is istio-system.

    $ export GATEWAY_URL=$(oc -n istio-system get route istio-ingressgateway -o jsonpath='{.spec.host}')

Adding default destination rules

Before you can use the Bookinfo application, you must first add default destination rules. There are two preconfigured YAML files, depending on whether or not you enabled mutual transport layer security (TLS) authentication.

Procedure
  1. To add destination rules, run one of the following commands:

    • If you did not enable mutual TLS:

      $ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-2.0/samples/bookinfo/networking/destination-rule-all.yaml
    • If you enabled mutual TLS:

      $ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-2.0/samples/bookinfo/networking/destination-rule-all-mtls.yaml

      You should see output similar to the following:

      destinationrule.networking.istio.io/productpage created
      destinationrule.networking.istio.io/reviews created
      destinationrule.networking.istio.io/ratings created
      destinationrule.networking.istio.io/details created

Verifying the Bookinfo installation

To confirm that the sample Bookinfo application was successfully deployed, perform the following steps.

Prerequisites
  • Red Hat OpenShift Service Mesh 2.0.8 installed.

  • Access to the OpenShift CLI (oc).

  • Complete the steps for installing the Bookinfo sample app.

Procedure
  1. Log in to the OpenShift Container Platform CLI.

  2. Verify that all pods are ready with this command:

    $ oc get pods -n bookinfo

    All pods should have a status of Running. You should see output similar to the following:

    NAME                              READY   STATUS    RESTARTS   AGE
    details-v1-55b869668-jh7hb        2/2     Running   0          12m
    productpage-v1-6fc77ff794-nsl8r   2/2     Running   0          12m
    ratings-v1-7d7d8d8b56-55scn       2/2     Running   0          12m
    reviews-v1-868597db96-bdxgq       2/2     Running   0          12m
    reviews-v2-5b64f47978-cvssp       2/2     Running   0          12m
    reviews-v3-6dfd49b55b-vcwpf       2/2     Running   0          12m
  3. Run the following command to retrieve the URL for the product page:

    echo "http://$GATEWAY_URL/productpage"
  4. Copy and paste the output in a web browser to verify the Bookinfo product page is deployed.

Removing the Bookinfo application

Follow these steps to remove the Bookinfo application.

Prerequisites
  • OpenShift Container Platform 4.1 or higher installed.

  • Red Hat OpenShift Service Mesh 2.0.8 installed.

  • Access to the OpenShift CLI (oc).

Delete the Bookinfo project

Procedure
  1. Log in to the OpenShift Container Platform web console.

  2. Click to HomeProjects.

  3. Click the bookinfo menu kebab, and then click Delete Project.

  4. Type bookinfo in the confirmation dialog box, and then click Delete.

    • Alternatively, you can run this command from the CLI to create the bookinfo project.

      $ oc delete project bookinfo

Remove the Bookinfo project from the Service Mesh member roll

Procedure
  1. Log in to the OpenShift Container Platform web console.

  2. Click OperatorsInstalled Operators.

  3. Click the Project menu and choose openshift-operators from the list.

  4. Click the Istio Service Mesh Member Roll link under Provided APIS for the Red Hat OpenShift Service Mesh Operator.

  5. Click the ServiceMeshMemberRoll menu kebab and select Edit Service Mesh Member Roll.

  6. Edit the default Service Mesh Member Roll YAML and remove bookinfo from the members list.

    • Alternatively, you can run this command from the CLI to remove the bookinfo project from the ServiceMeshMemberRoll. In this example, istio-system is the name of the control plane project.

      $ oc -n istio-system patch --type='json' smmr default -p '[{"op": "remove", "path": "/spec/members", "value":["'"bookinfo"'"]}]'
  7. Click Save to update Service Mesh Member Roll.

Generating example traces and analyzing trace data

Jaeger is an open source distributed tracing system. With Jaeger, you can perform a trace that follows the path of a request through various microservices which make up an application. Jaeger is installed by default as part of the Service Mesh.

This tutorial uses Service Mesh and the Bookinfo sample application to demonstrate how you can use Jaeger to perform distributed tracing.

Prerequisites:
  • OpenShift Container Platform 4.1 or higher installed.

  • Red Hat OpenShift Service Mesh 2.0.8 installed.

  • Jaeger enabled during the installation.

  • Bookinfo example application installed.

Procedure
  1. After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command several times.

    $ curl "http://$GATEWAY_URL/productpage"

    This command simulates a user visiting the productpage microservice of the application.

  2. In the OpenShift Container Platform console, navigate to NetworkingRoutes and search for the Jaeger route, which is the URL listed under Location.

    • Alternatively, use the CLI to query for details of the route. In this example, istio-system is the control plane namespace:

      $ export JAEGER_URL=$(oc get route -n istio-system jaeger -o jsonpath='{.spec.host}')
      1. Enter the following command to reveal the URL for the Jaeger console. Paste the result in a browser and navigate to that URL.

        echo $JAEGER_URL
  3. Log in using the same user name and password as you use to access the OpenShift Container Platform console.

  4. In the left pane of the Jaeger dashboard, from the Service menu, select productpage.bookinfo and click the Find Traces button at the bottom of the pane. A list of traces is displayed.

  5. Click one of the traces in the list to open a detailed view of that trace. If you click the first one in the list, which is the most recent trace, you see the details that correspond to the latest refresh of the /productpage.