Chapter 1. Service Mesh 1.x

Procedure

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

2. Create a project named istio-system.

   1. Navigate to Home Projects.
   2. Click Create Project.
   3. Enter istio-system in the Name field.
   4. Click Create.
3. Navigate to Operators Installed 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 ServiceMeshControlPlane.

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

   Note

   For additional information about customizing the control plane, see customizing the Red Hat OpenShift Service Mesh installation. For production, 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.

Procedure

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

   $ oc login https://{HOSTNAME}:6443

2. Create a project named istio-system.

   $ oc new-project istio-system

3. Create a ServiceMeshControlPlane file named istio-installation.yaml using the example found in "Customize the Red Hat OpenShift Service Mesh installation". You can customize the values as needed to match your use case. For production deployments 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:

   Example output

   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                   1/1     Running            0          22h
   prometheus-6dff867c97-gr2n5              2/2     Running            0          28h

Procedure

1. If you don’t already have projects for your mesh, or you are starting from scratch, create a project. It must be different from istio-system.

   1. Navigate to Home Projects.
   2. Enter a name in the Name field.
   3. Click Create.
2. Log in to the OpenShift Container Platform web console.
3. Navigate to Operators Installed Operators.
4. Click the Project menu and choose the project where your ServiceMeshControlPlane is deployed from the list, for example istio-system.
5. Click the Red Hat OpenShift Service Mesh Operator.
6. Click the All Instances tab.

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

   Note

   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.

8. 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.
9. Click Create to save the Service Mesh Member Roll.

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.

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

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

Procedure

1. Log in to the OpenShift Container Platform web console as a user with the cluster-admin role.
2. Navigate to Operators Installed Operators.
3. Click the Red Hat OpenShift Service Mesh Operator.
4. Click the Istio Service Mesh Control Plane tab.
5. Click the name of your control plane file, for example, basic-install.
6. Click the YAML tab.
7. Edit the Jaeger parameters, replacing the default all-in-one template with parameters for the production-elasticsearch template, modified for your use case. Ensure that the indentation is correct.
8. Click Save.
9. Click Reload. OpenShift Container Platform redeploys Jaeger and creates the Elasticsearch resources based on the specified parameters.

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

Procedure

1. Open the application’s configuration YAML file in an editor.

2. Add sidecar.istio.io/inject to the configuration YAML with a value of "true" as illustrated here:

   Sleep test application example

   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: tutum/curl
           command: ["/bin/sleep","infinity"]
           imagePullPolicy: IfNotPresent

3. Save the configuration file.

Procedure

1. Log in to the OpenShift Container Platform web console as a user with cluster-admin rights.
2. Click to 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 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 link.

   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 Istio Service Mesh Member Roll, click Create Service Mesh Member Roll.

      Note

      You need cluster-admin rights to edit the Istio Service Mesh Member Roll.

9. Edit the default Service Mesh Member Roll YAML and add bookinfo to the members list.

   Bookinfo ServiceMeshMemberRoll example

     apiVersion: maistra.io/v1
     kind: ServiceMeshMemberRoll
     metadata:
       name: default
     spec:
       members:
       - bookinfo

   • Alternatively, you can run this command from the CLI to add the bookinfo project to the ServiceMeshMemberRoll. Replace <control_plane_project> with the name of your control plane project.

     $ oc -n <control_plane_project> patch --type='json' smmr default -p '[{"op": "add", "path": "/spec/members", "value":["'"bookinfo"'"]}]'

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

11. 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-1.1/samples/bookinfo/platform/kube/bookinfo.yaml

12. Create the ingress gateway by applying the bookinfo-gateway.yaml file:

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

13. Set the value for the GATEWAY_URL parameter:

    Note

    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 <control_plane_project> get route istio-ingressgateway -o jsonpath='{.spec.host}')

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-1.1/samples/bookinfo/networking/destination-rule-all.yaml

   • If you enabled mutual TLS:

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

Procedure

1. Log in to the OpenShift Container Platform CLI.

2. Run this command to confirm that Bookinfo is deployed:

   $ curl -o /dev/null -s -w "%{http_code}\n" http://$GATEWAY_URL/productpage

   • Alternatively, you can open http://$GATEWAY_URL/productpage in your browser.

   • You can also verify that all pods are ready with this command:

     $ oc get pods -n bookinfo

1. Click Graph in the main navigation.
2. Select bookinfo from the Namespace menu.

1. Create a secret cacert that includes the input files ca-cert.pem, ca-key.pem, root-cert.pem and cert-chain.pem.

   $ oc create secret generic cacerts -n istio-system --from-file=<path>/ca-cert.pem \
       --from-file=<path>/ca-key.pem --from-file=<path>/root-cert.pem \
       --from-file=<path>/cert-chain.pem

2. In the ServiceMeshControlPlane resource set global.mtls.enabled to true and security.selfSigned set to false. Service Mesh reads the certificates and key from the secret-mount files.

   apiVersion: maistra.io/v1
   kind: ServiceMeshControlPlane
   spec:
     istio:
       global:
         mtls:
           enabled: true
       security:
         selfSigned: false

3. To make sure the workloads add the new certificates promptly, delete the secrets generated by Service Mesh, named istio.*. In this example, istio.default. Service Mesh issues new certificates for the workloads.

   $ oc delete secret istio.default

1. Store the pod name in the variable RATINGSPOD.

   $ RATINGSPOD=`oc get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'`

2. Run the following commands to retrieve the certificates mounted on the proxy.

   $ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/root-cert.pem > /tmp/pod-root-cert.pem

   The file /tmp/pod-root-cert.pem contains the root certificate propagated to the pod.

   $ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem

   The file /tmp/pod-cert-chain.pem contains the workload certificate and the CA certificate propagated to the pod.

3. Verify the root certificate is the same as the one specified by the Operator. Replace <path> with the path to your certificates.

   $ openssl x509 -in <path>/root-cert.pem -text -noout > /tmp/root-cert.crt.txt

   $ openssl x509 -in /tmp/pod-root-cert.pem -text -noout > /tmp/pod-root-cert.crt.txt

   $ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt

   Expect the output to be empty.

4. Verify the CA certificate is the same as the one specified by Operator. Replace <path> with the path to your certificates.

   $ sed '0,/^-----END CERTIFICATE-----/d' /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-ca.pem

   $ openssl x509 -in <path>/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt

   $ openssl x509 -in /tmp/pod-cert-chain-ca.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt

   $ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt

   Expect the output to be empty.

5. Verify the certificate chain from the root certificate to the workload certificate. Replace <path> with the path to your certificates.

   $ head -n 21 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-workload.pem

   $ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) /tmp/pod-cert-chain-workload.pem

   Example output

   /tmp/pod-cert-chain-workload.pem: OK

1. Remove the secret cacerts.

   $ oc delete secret cacerts -n istio-system

2. Redeploy Service Mesh with a self-signed root certificate in the ServiceMeshControlPlane resource.

   apiVersion: maistra.io/v1
   kind: ServiceMeshControlPlane
   spec:
     istio:
       global:
         mtls:
           enabled: true
       security:
         selfSigned: true

1. Run the following command to apply the virtual services:

   $ oc apply -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/virtual-service-all-v1.yaml

2. To test the command was successful, display the defined routes with the following command:

   $ oc get virtualservices -o yaml

   That command returns the following YAML file.

   apiVersion: networking.istio.io/v1alpha3
   kind: VirtualService
   metadata:
     name: details
     ...
   spec:
     hosts:
     - details
     http:
     - route:
       - destination:
         host: details
         subset: v1
   ---
   apiVersion: networking.istio.io/v1alpha3
   kind: VirtualService
   metadata:
     name: productpage
     ...
   spec:
     gateways:
     - bookinfo-gateway
     - mesh
     hosts:
     - productpage
     http:
     - route:
       - destination:
         host: productpage
         subset: v1
   ---
   apiVersion: networking.istio.io/v1alpha3
   kind: VirtualService
   metadata:
     name: ratings
     ...
   spec:
     hosts:
     - ratings
     http:
     - route:
       - destination:
         host: ratings
         subset: v1
   ---
   apiVersion: networking.istio.io/v1alpha3
   kind: VirtualService
   metadata:
     name: reviews
     ...
   spec:
     hosts:
     - reviews
     http:
     - route:
       - destination:
         host: reviews
         subset: v1

   You have configured Service Mesh to route to the v1 version of the Bookinfo microservices, most importantly the reviews service version 1.

1. Open the Bookinfo site in your browser. The URL is http://$GATEWAY_URL/productpage, where $GATEWAY_URL is the External IP address of the ingress.

   The reviews part of the page displays with no rating stars, no matter how many times you refresh. This is because you configured Service Mesh to route all traffic for the reviews service to the version reviews:v1 and this version of the service does not access the star ratings service.

   Your service mesh now routes traffic to one version of a service.

1. Run the following command to enable user-based routing:

   $ oc apply -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/virtual-service-reviews-test-v2.yaml

2. Confirm the rule is created:

   $ oc get virtualservice reviews -o yaml

   That command returns the following YAML file.

   apiVersion: networking.istio.io/v1alpha3
   kind: VirtualService
   metadata:
     name: reviews
     ...
   spec:
     hosts:
     - reviews
     http:
     - match:
       - headers:
         end-user:
           exact: jason
       route:
       - destination:
         host: reviews
         subset: v2
     - route:
       - destination:
         host: reviews
         subset: v1

3. On the /productpage of the Bookinfo app, log in as user jason. Refresh the browser. What do you see? The star ratings appear next to each review.
4. Log in as another user (pick any name you wish). Refresh the browser. Now the stars are gone. This is because traffic is routed to reviews:v1 for all users except Jason.

1. Run this command to generate manifests from a deployed adapter in the istio-system namespace:

   $ export NS="istio-system" URL="https://replaceme-admin.3scale.net:443" NAME="name" TOKEN="token"
   oc exec -n ${NS} $(oc get po -n ${NS} -o jsonpath='{.items[?(@.metadata.labels.app=="3scale-istio-adapter")].metadata.name}') \
   -it -- ./3scale-config-gen \
   --url ${URL} --name ${NAME} --token ${TOKEN} -n ${NS}

2. This will produce sample output to the terminal. Edit these samples if required and create the objects using the oc create command.

3. When the request reaches the adapter, the adapter needs to know how the service maps to an API on 3scale. You can provide this information in two ways:

   1. Label the workload (recommended)
   2. Hard code the handler as service_id

4. Update the workload with the required annotations:

   Note

   You only need to update the service ID provided in this example if it is not already embedded in the handler. The setting in the handler takes precedence.

   $ export CREDENTIALS_NAME="replace-me"
   export SERVICE_ID="replace-me"
   export DEPLOYMENT="replace-me"
   patch="$(oc get deployment "${DEPLOYMENT}"
   patch="$(oc get deployment "${DEPLOYMENT}" --template='{"spec":{"template":{"metadata":{"labels":{ {{ range $k,$v := .spec.template.metadata.labels }}"{{ $k }}":"{{ $v }}",{{ end }}"service-mesh.3scale.net/service-id":"'"${SERVICE_ID}"'","service-mesh.3scale.net/credentials":"'"${CREDENTIALS_NAME}"'"}}}}}' )"
   oc patch deployment "${DEPLOYMENT}" --patch ''"${patch}"''

Procedure

1. Match the rule destination.labels["service-mesh.3scale.net/credentials"] == "threescale" that you previously created in the configuration, in the kind: rule resource.
2. Add the above label to PodTemplateSpec on the Deployment of the target workload to integrate a service. the value, threescale, refers to the name of the generated handler. This handler stores the access token required to call 3scale.
3. Add the destination.labels["service-mesh.3scale.net/service-id"] == "replace-me" label to the workload to pass the service ID to the adapter via the instance at request time.

Procedure

1. Log in to the OpenShift Container Platform web console.
2. Click the Project menu and choose the istio-system project from the list.
3. Navigate to Operators Installed Operators.
4. Click on Service Mesh Control Plane under Provided APIs.
5. Click the ServiceMeshControlPlane menu .
6. Click Delete Service Mesh Control Plane.
7. Click Delete on the confirmation dialog window to remove the ServiceMeshControlPlane.

1. Log in to the OpenShift Container Platform CLI.

2. Run this command to retrieve the name of the installed ServiceMeshControlPlane:

   $ oc get servicemeshcontrolplanes -n istio-system

3. Replace <name_of_custom_resource> with the output from the previous command, and run this command to remove the custom resource:

   $ oc delete servicemeshcontrolplanes -n istio-system <name_of_custom_resource>

Procedure

1. Log in to the OpenShift Container Platform web console.
2. From the Operators Installed Operators page, scroll or type a keyword into the Filter by name to find the Red Hat OpenShift Service Mesh Operator. Then, click on it.
3. On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
4. When prompted by the Remove Operator Subscription window, optionally select the Also completely remove the Operator from the selected namespace check box if you want all components related to the installation to be removed. This removes the CSV, which in turn removes the pods, Deployments, CRDs, and CRs associated with the Operator.

Procedure

1. Log in to the OpenShift Container Platform web console.
2. From the Operators Installed Operators page, scroll or type a keyword into the Filter by name to find the Jaeger Operator. Then, click on it.
3. On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
4. When prompted by the Remove Operator Subscription window, optionally select the Also completely remove the Operator from the selected namespace check box if you want all components related to the installation to be removed. This removes the CSV, which in turn removes the pods, Deployments, CRDs, and CRs associated with the Operator.

Procedure

1. Log in to the OpenShift Container Platform web console.
2. From the Operators Installed Operators page, scroll or type a keyword into the Filter by name to find the Kiali Operator. Then, click on it.
3. On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
4. When prompted by the Remove Operator Subscription window, optionally select the Also completely remove the Operator from the selected namespace check box if you want all components related to the installation to be removed. This removes the CSV, which in turn removes the pods, Deployments, CRDs, and CRs associated with the Operator.

Procedure

1. Log in to the OpenShift Container Platform web console.
2. From the Operators Installed Operators page, scroll or type a keyword into the Filter by name to find the Elasticsearch Operator. Then, click on it.
3. On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
4. When prompted by the Remove Operator Subscription window, optionally select the Also completely remove the Operator from the selected namespace check box if you want all components related to the installation to be removed. This removes the CSV, which in turn removes the pods, Deployments, CRDs, and CRs associated with the Operator.

Procedure

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

2. Run the following commands to clean up resources after uninstalling the Operators:

   Note

   Replace <operator-project> with the name of the project where the Red Hat OpenShift Service Mesh Operator was installed. This is typically openshift-operators.

   $ oc delete validatingwebhookconfiguration/<operator-project>.servicemesh-resources.maistra.io

   $ oc delete mutatingwebhookconfigurations/<operator-project>.servicemesh-resources.maistra.io

   $ oc delete -n <operator-project> daemonset/istio-node

   $ oc delete clusterrole/istio-admin clusterrole/istio-cni clusterrolebinding/istio-cni

   $ oc get crds -o name | grep '.*\.istio\.io' | xargs -r -n 1 oc delete

   $ oc get crds -o name | grep '.*\.maistra\.io' | xargs -r -n 1 oc delete

   $ oc get crds -o name | grep '.*\.kiali\.io' | xargs -r -n 1 oc delete