Installing the Service Mesh involves installing the Elasticsearch, Jaeger, Kiali and Service Mesh Operators, creating and managing a ServiceMeshControlPlane resource to deploy the control plane, and creating a ServiceMeshMemberRoll resource to specify the namespaces associated with the Service Mesh.

Mixer’s policy enforcement is disabled by default. You must enable it to run policy tasks. See Update Mixer policy enforcement for instructions on enabling Mixer policy enforcement.

Multi-tenant control plane installations are the default configuration starting with Red Hat OpenShift Service Mesh 1.0.

The Service Mesh documentation uses istio-system as the example project, but you may deploy the service mesh to any project.

Prerequisites

Installing the Operators from OperatorHub

The Service Mesh installation process uses the OperatorHub to install the ServiceMeshControlPlane custom resource definition within the openshift-operators project. The Red Hat OpenShift Service Mesh defines and monitors the ServiceMeshControlPlane related to the deployment, update, and deletion of the control plane.

Starting with Red Hat OpenShift Service Mesh 1.0.2, you must install the Elasticsearch Operator, the Jaeger Operator, and the Kiali Operator before the Red Hat OpenShift Service Mesh Operator can install the control plane.

Installing the Elasticsearch Operator

You must install the Elasticsearch Operator for the Red Hat OpenShift Service Mesh Operator to install the control plane.

Do not install Community versions of the Operators. Community Operators are not supported.

Prerequisites
  • Access to the OpenShift Container Platform web console.

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

  2. Navigate to OperatorsOperatorHub.

  3. Type Elasticsearch into the filter box to locate the Elasticsearch Operator.

  4. Click the Elasticsearch Operator to display information about the Operator.

  5. Click Install.

  6. On the Create Operator Subscription page, select All namespaces on the cluster (default). This installs the Operator in the default openshift-operators project and makes the Operator available to all projects in the cluster.

  7. Select the preview Update Channel.

  8. Select the Automatic Approval Strategy.

    The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process.

  9. Click Subscribe.

  10. The Subscription Overview page displays the Elasticsearch Operator’s installation progress.

Installing the Jaeger Operator

You must install the Jaeger Operator for the Red Hat OpenShift Service Mesh Operator to install the control plane.

Do not install Community versions of the Operators. Community Operators are not supported.

Prerequisites
  • Access to the OpenShift Container Platform web console.

  • The Elasticsearch Operator must be installed.

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

  2. Navigate to OperatorsOperatorHub.

  3. Type Jaeger into the filter box to locate the Jaeger Operator.

  4. Click the Jaeger Operator provided by Red Hat to display information about the Operator.

  5. Click Install.

  6. On the Create Operator Subscription page, select All namespaces on the cluster (default). This installs the Operator in the default openshift-operators project and makes the Operator available to all projects in the cluster.

  7. Select the stable Update Channel.

  8. Select the Automatic Approval Strategy.

    The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process.

  9. Click Subscribe.

  10. The Subscription Overview page displays the Jaeger Operator’s installation progress.

Installing the Kiali Operator

You must install the Kiali Operator for the Red Hat OpenShift Service Mesh Operator to install the control plane.

Do not install Community versions of the Operators. Community Operators are not supported.

Prerequisites
  • Access to the OpenShift Container Platform web console.

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

  2. Navigate to OperatorsOperatorHub.

  3. Type Kiali into the filter box to find the Kiali Operator.

  4. Click the Kiali Operator provided by Red Hat to display information about the Operator.

  5. Click Install.

  6. On the Create Operator Subscription page, select All namespaces on the cluster (default). This installs the Operator in the default openshift-operators project and makes the Operator available to all projects in the cluster.

  7. Select the stable Update Channel.

  8. Select the Automatic Approval Strategy.

    The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process.

  9. Click Subscribe.

  10. The Subscription Overview page displays the Kiali Operator’s installation progress.

Installing the Red Hat OpenShift Service Mesh Operator

Prerequisites
  • Access to the OpenShift Container Platform web console.

  • The Elasticsearch Operator must be installed.

  • The Jaeger Operator must be installed.

  • The Kiali Operator must be installed.

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

  2. Navigate to OperatorsOperatorHub.

  3. Type Red Hat OpenShift Service Mesh into the filter box to find the Red Hat OpenShift Service Mesh Operator.

  4. Click the Red Hat OpenShift Service Mesh Operator to display information about the Operator.

  5. On the Create Operator Subscription page, select All namespaces on the cluster (default). This installs the Operator in the default openshift-operators project and makes the Operator available to all projects in the cluster.

  6. Click Install.

  7. Select the 1.0 Update Channel.

  8. Select the Automatic Approval Strategy.

    The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process.

  9. Click Subscribe.

  10. The Subscription Overview page displays the Red Hat OpenShift Service Mesh Operator’s installation progress.

Deploying the Red Hat OpenShift Service Mesh control plane

The ServiceMeshControlPlane resource defines the configuration to be used during installation. You can deploy the default configuration provided by Red Hat or customize the ServiceMeshControlPlane file to fit your business needs.

You can deploy the Service Mesh control plane by using the OpenShift Container Platform web console or from the command line using the oc client tool.

Deploying the control plane from the web console

Follow this procedure to deploy the Red Hat OpenShift Service Mesh control plane by using the web console.

Prerequisites
  • The Red Hat OpenShift Service Mesh Operator must be installed.

  • Review the instructions for how to customize the Red Hat OpenShift Service Mesh installation.

  • An account with the cluster-admin role.

Procedure
  1. Log in to the OpenShift Container Platform web console as a user with the cluster-admin role.

  2. Create a new project named istio-system.

    1. Navigate to HomeProjects.

    2. Click Create Project.

    3. Enter istio-system in the Name field.

    4. Click Create.

  3. Navigate to CatalogsInstalled Operators.

  4. If necessary, select istio-system from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project.

  5. Click the Red Hat OpenShift Service Mesh Operator. Under Provided APIs, the Operator provides links to create two resource types:

    • A ServiceMeshControlPlane resource

    • A ServiceMeshMemberRoll resource

  6. Under Istio Service Mesh Control Plane click Create New.

  7. On the Create Service Mesh Control Plane page, modify the YAML for the default ServiceMeshControlPlane template as needed.

    For additional information about customizing the control plane, see customizing the Red Hat OpenShift Service Mesh installation. Note that for production use you must change the default Jaeger template.

  8. Click Create to create the control plane. The Operator creates Pods, services, and Service Mesh control plane components based on your configuration parameters.

  9. Click the Istio Service Mesh Control Plane tab.

  10. Click the name of the new control plane.

  11. Click the Resources tab to see the Red Hat OpenShift Service Mesh control plane resources the Operator created and configured.

Deploying the control plane from the CLI

Follow this procedure to deploy the Red Hat OpenShift Service Mesh control plane the command line.

Prerequisites
  • The Red Hat OpenShift Service Mesh Operator must be installed.

  • Review the instructions for how to customize the Red Hat OpenShift Service Mesh installation.

  • An account with the cluster-admin role.

  • Access to the OpenShift Container Platform Command-line Interface (CLI), commonly known as oc.

Procedure
  1. Log in to the OpenShift Container Platform CLI as a user with the cluster-admin role.

    $ oc login https://{HOSTNAME}:8443
  2. Create a new project named istio-system.

    $ oc new-project istio-system
  3. Create a ServiceMeshControlPlane file named istio-installation.yaml using the full example found in "Customize the Red Hat OpenShift Service Mesh installation". You can customize the values as needed to match your use case. Note that for production use you must change the default Jaeger template.

  4. Run the following command to deploy the control plane:

    $ oc create -n istio-system -f istio-installation.yaml
  5. Execute the following command to see the status of the control plane installation.

    $ oc get smcp -n istio-system

    The installation has finished successfully when the READY column is true.

    NAME           READY
    basic-install   True
  6. Run the following command to watch the progress of the Pods during the installation process:

    $ oc get pods -n istio-system -w

    You should see output similar to the following:

    NAME                                     READY   STATUS             RESTARTS   AGE
    grafana-7bf5764d9d-2b2f6                 2/2     Running            0          28h
    istio-citadel-576b9c5bbd-z84z4           1/1     Running            0          28h
    istio-egressgateway-5476bc4656-r4zdv     1/1     Running            0          28h
    istio-galley-7d57b47bb7-lqdxv            1/1     Running            0          28h
    istio-ingressgateway-dbb8f7f46-ct6n5     1/1     Running            0          28h
    istio-pilot-546bf69578-ccg5x             2/2     Running            0          28h
    istio-policy-77fd498655-7pvjw            2/2     Running            0          28h
    istio-sidecar-injector-df45bd899-ctxdt   1/1     Running            0          28h
    istio-telemetry-66f697d6d5-cj28l         2/2     Running            0          28h
    jaeger-896945cbc-7lqrr                   2/2     Running            0          11h
    kiali-78d9c5b87c-snjzh                   0/1     Running            0          22h
    prometheus-6dff867c97-gr2n5              2/2     Running            0          28h

For a multitenant installation, Red Hat OpenShift Service Mesh supports multiple independent control planes within the cluster. You can create reusable configurations with ServiceMeshControlPlane templates. For more information, see Creating control plane templates.

Creating the Red Hat OpenShift Service Mesh member roll

The ServiceMeshMemberRoll lists the projects belonging to the 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.

The member projects are only updated if the Service Mesh control plane installation succeeds.

Creating the member roll from the web console

Follow this procedure to add one or more projects to the Service Mesh member roll by using the web console.

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

  • Location of the installed ServiceMeshControlPlane.

  • List of projects to add to the service mesh.

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

  2. Navigate to CatalogsInstalled Operators.

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

  4. Click the Red Hat OpenShift Service Mesh Operator.

  5. Click the All Instances tab.

  6. Click Create New, and then select Create Istio Service Mesh Member Roll.

    It can take a short time for the Operator to finish copying the resources, therefore you may need to refresh the screen to see the Create Istio Service Mesh Member Roll button.

  7. On the Create Service Mesh Member Roll page, modify the YAML to add your projects as members. You can add any number of projects, but a project can only belong to one ServiceMeshMemberRoll resource.

  8. Click Create to save the Service Mesh Member Roll.

Creating the member roll from the CLI

Follow this procedure to add a project to the ServiceMeshMemberRoll from the command line.

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

  • Location of the installed ServiceMeshControlPlane.

  • List of projects to add to the service mesh.

  • Access to the OpenShift Container Platform Command-line Interface (CLI) commonly known as oc.

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

    $ oc login
  2. Create a ServiceMeshMemberRoll resource in the same project as the ServiceMeshControlPlane resource, in our example that is istio-system. The resource must be named default.

    $ oc create -n istio-system -f servicemeshmemberroll-default.yaml
    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
  3. Modify the default YAML to add your projects as members. You can add any number of projects, but a project can only belong to one ServiceMeshMemberRoll resource.

Adding or removing projects from the service mesh

Follow this procedure to modify 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.

Modifying the member roll from 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 CatalogsInstalled Operators.

  3. Click the Project menu and choose the project where your ServiceMeshControlPlane 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.

Modifying the member roll from the CLI

Follow this procedure to 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 Container Platform Command-line Interface (CLI) commonly known as 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
    spec:
      members:
        # a list of projects joined into the service mesh
        - your-project-name
        - another-project-name

Deleting the Red Hat OpenShift Service Mesh member roll

The ServiceMeshMemberRoll resource is automatically deleted when you delete the ServiceMeshControlPlane resource it is associated with.

Updating your application pods

If you selected the Automatic Approval Strategy when you were installing your Operators, then the Operators update the control plane automatically, but not your applications. Existing applications continue to be part of the mesh and function accordingly. The application administrator must restart applications to upgrade the sidecar.

If your deployment uses Automatic sidecar injection, you can update the pod template in the deployment by adding or modifying an annotation. Run the following command to redeploy the pods:

$ oc patch deployment/<deployment> -p '{"spec":{"template":{"metadata":{"annotations":{"kubectl.kubernetes.io/restartedAt": "'`date -Iseconds`'"}}}}}'

If your deployment does not use automatic sidecar injection, you must manually update the sidecars by modifying the sidecar container image specified in the deployment or pod.