OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Adding services to a service mesh

After installing the Operators and ServiceMeshControlPlane resource, add applications, workloads, or services to your mesh by creating a ServiceMeshMemberRoll resource and specifying the namespaces where your content is located. If you already have an application, workload, or service to add to a ServiceMeshMemberRoll resource, use the following steps. Or, to install a sample application called Bookinfo and add it to a ServiceMeshMemberRoll resource, skip to the tutorial for installing the Bookinfo example application to see how an application works in Red Hat OpenShift Service Mesh.

The items listed in the ServiceMeshMemberRoll resource are the applications and workflows that are managed by the ServiceMeshControlPlane resource. The control plane, which includes the Service Mesh Operators, Istiod, and ServiceMeshControlPlane, and the data plane, which includes applications and Envoy proxy, must be in separate namespaces.

After you add the namespace to the ServiceMeshMemberRoll, access to services or pods in that namespace will not be accessible to callers outside the service mesh.

Creating the Red Hat OpenShift Service Mesh member roll

The ServiceMeshMemberRoll lists the projects that belong to the Service Mesh control plane. Only projects listed in the ServiceMeshMemberRoll are affected by the control plane. A project does not belong to a service mesh until you add it to the member roll for a particular control plane deployment.

You must create a ServiceMeshMemberRoll resource named default in the same project as the ServiceMeshControlPlane, for example istio-system.

Creating the member roll from the web console

You can add one or more projects to the Service Mesh member roll from the web console. In this example, istio-system is the name of the Service Mesh control plane project.

Prerequisites

  • An installed, verified Red Hat OpenShift Service Mesh Operator.

  • List of existing projects to add to the service mesh.

Procedure

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

  2. If you do not already have services for your mesh, or you are starting from scratch, create a project for your applications. It must be different from the project where you installed the Service Mesh control plane.

    1. Navigate to Home → Projects.

    2. Enter a name in the Name field.

    3. Click Create.

  3. Navigate to Operators → Installed Operators.

  4. Click the Project menu and choose the project where your ServiceMeshControlPlane resource is deployed from the list, for example istio-system.

  5. Click the Red Hat OpenShift Service Mesh Operator.

  6. Click the Istio Service Mesh Member Roll tab.

  7. Click Create ServiceMeshMemberRoll

  8. Click Members, then enter the name of your project in the Value field. You can add any number of projects, but a project can only belong to one ServiceMeshMemberRoll resource.

  9. Click Create.

Creating the member roll from the CLI

You can add a project to the ServiceMeshMemberRoll from the command line.

Prerequisites

  • An installed, verified Red Hat OpenShift Service Mesh Operator.

  • List of projects to add to the service mesh.

  • Access to the OpenShift CLI (oc).

Procedure

  1. Log in to the OpenShift Container Platform CLI.

    $ oc login --username=<NAMEOFUSER> https://<HOSTNAME>:6443

  2. If you do not already have services for your mesh, or you are starting from scratch, create a project for your applications. It must be different from the project where you installed the Service Mesh control plane.

    $ oc new-project <your-project>

  3. To add your projects as members, modify the following example YAML. You can add any number of projects, but a project can only belong to one ServiceMeshMemberRoll resource. In this example, istio-system is the name of the Service Mesh control plane project.

    Example servicemeshmemberroll-default.yaml
    apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
  name: default
  namespace: istio-system
spec:
  members:
    # a list of projects joined into the service mesh
    - your-project-name
    - another-project-name

  4. Run the following command to upload and create the ServiceMeshMemberRoll resource in the istio-system namespace.

    $ oc create -n istio-system -f servicemeshmemberroll-default.yaml

  5. Run the following command to verify the ServiceMeshMemberRoll was created successfully.

    $ oc get smmr -n istio-system default

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

Adding or removing projects from the service mesh

You can add or remove projects from an existing Service Mesh ServiceMeshMemberRoll resource using the web console.

  • You can add any number of projects, but a project can only belong to one ServiceMeshMemberRoll resource.

  • The ServiceMeshMemberRoll resource is deleted when its corresponding ServiceMeshControlPlane resource is deleted.

Adding or removing projects from the member roll using the web console

Prerequisites

  • An installed, verified Red Hat OpenShift Service Mesh Operator.

  • An existing ServiceMeshMemberRoll resource.

  • Name of the project with the ServiceMeshMemberRoll resource.

  • Names of the projects you want to add or remove from the mesh.

Procedure

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

  2. Navigate to Operators → Installed Operators.

  3. Click the Project menu and choose the project where your ServiceMeshControlPlane resource is deployed from the list, for example istio-system.

  4. Click the Red Hat OpenShift Service Mesh Operator.

  5. Click the Istio Service Mesh Member Roll tab.

  6. Click the default link.

  7. Click the YAML tab.

  8. Modify the YAML to add or remove projects as members. You can add any number of projects, but a project can only belong to one ServiceMeshMemberRoll resource.

  9. Click Save.

  10. Click Reload.

Adding or removing projects from the member roll using the CLI

You can modify an existing Service Mesh member roll using the command line.

Prerequisites

  • An installed, verified Red Hat OpenShift Service Mesh Operator.

  • An existing ServiceMeshMemberRoll resource.

  • Name of the project with the ServiceMeshMemberRoll resource.

  • Names of the projects you want to add or remove from the mesh.

  • Access to the OpenShift CLI (oc).

Procedure

  1. Log in to the OpenShift Container Platform CLI.

  2. Edit the ServiceMeshMemberRoll resource.

    $ oc edit smmr -n <controlplane-namespace>

  3. Modify the YAML to add or remove projects as members. You can add any number of projects, but a project can only belong to one ServiceMeshMemberRoll resource.

    Example servicemeshmemberroll-default.yaml
    apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
  name: default
  namespace: istio-system #control plane project
spec:
  members:
    # a list of projects joined into the service mesh
    - your-project-name
    - another-project-name

Bookinfo example application

The Bookinfo example application allows you to test your Red Hat OpenShift Service Mesh 2.2.3 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.2.3 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.

The commands in this section assume the Service Mesh control plane project is istio-system. If you installed the control plane in another namespace, edit each command before you run it.
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 Home → Projects.

  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 Operators → Installed Operators.

  6. Click the Project menu and use the Service Mesh 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 Service Mesh 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 -o wide

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

    NAME      READY   STATUS       AGE   MEMBERS
default   1/1     Configured   70s   ["bookinfo"]

  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.2/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.2/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:

    $ 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.2/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.2/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 installed.

  • Complete the steps for installing the Bookinfo sample app.

Procedure from CLI

  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.

Procedure from Kiali web console

  1. Obtain the address for the Kiali web console.

    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. Navigate to Networking → Routes.

    3. On the Routes page, select the Service Mesh control plane project, for example istio-system, from the Namespace menu.

      The Location column displays the linked address for each route.

    4. Click the link in the Location column for Kiali.

    5. Click Log In With OpenShift. The Kiali Overview screen presents tiles for each project namespace.

  2. In Kiali, click Graph.

  3. Select bookinfo from the Namespace list, and App graph from the Graph Type list.

  4. Click Display idle nodes from the Display menu.

    This displays nodes that are defined but have not received or sent requests. It can confirm that an application is properly defined, but that no request traffic has been reported.

    Kiali displaying bookinfo application

    • Use the Duration menu to increase the time period to help ensure older traffic is captured.

    • Use the Refresh Rate menu to refresh traffic more or less often, or not at all.

  5. Click Services, Workloads or Istio Config to see list views of bookinfo components, and confirm that they are healthy.

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.2.3 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 Home → Projects.

  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 using 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 Operators → Installed Operators.

  3. Click the Project menu and choose istio-system 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 using the CLI to remove the bookinfo project from the ServiceMeshMemberRoll. In this example, istio-system is the name of the Service Mesh 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.

Next steps