Chapter 1. Installing OpenShift Service Mesh Installing OpenShift Service Mesh consists of three main tasks: installing the OpenShift Operator, deploying Istio, and customizing the Istio configuration. Then, you can also choose to install the sample bookinfo application to push data through the mesh and explore mesh functionality. 1.1. About deploying Istio using the Red Hat OpenShift Service Mesh Operator To deploy Istio using the Red Hat OpenShift Service Mesh Operator, you must create an Istio resource. Then, the Operator creates an IstioRevision resource, which represents one revision of the Istio control plane. Based on the IstioRevision resource, the Operator deploys the Istio control plane, which includes the istiod Deployment resource and other resources. The Red Hat OpenShift Service Mesh Operator may create additional instances of the IstioRevision resource, depending on the update strategy defined in the Istio resource. 1.1.1. About update strategies The update strategy affects how the update process is performed. For each mesh, you select one of two strategies: InPlace RevisionBased The default strategy is the InPlace strategy. For more information, see the following documentation located in "Updating OpenShift Service Mesh": "About InPlace strategy" "About RevisionBased strategy" 1.2. Installing the Service Mesh Operator Prerequisites You have deployed a cluster on OpenShift Container Platform 4.14 or later. You are logged in to the OpenShift Container Platform web console as a user with the cluster-admin role. Procedure In the OpenShift Container Platform web console, navigate to the Operators OperatorHub page. Search for the Red Hat OpenShift Service Mesh 3 Operator. Locate the Service Mesh Operator, and click to select it. When the prompt that discusses the community operator appears, click Continue . Verify the Service Mesh Operator is version 3.0, and click Install . Use the default installation settings presented, and click Install to continue. Click Operators Installed Operators to verify that the Service Mesh Operator is installed. Succeeded should appear in the Status column. 1.2.1. About Service Mesh custom resource definitions Installing the Red Hat OpenShift Service Mesh Operator also installs custom resource definitions (CRD) that administrators can use to configure Istio for Service Mesh installations. The Operator Lifecycle Manager (OLM) installs two categories of CRDs: Sail Operator CRDs and Istio CRDs. Sail Operator CRDs define custom resources for installing and maintaining the Istio components required to operate a service mesh. These custom resources belong to the sailoperator.io API group and include the Istio , IstioRevision , IstioCNI , and ZTunnel resource kinds. For more information on how to configure these resources, see the sailoperator.io API reference documentation. Istio CRDs are associated with mesh configuration and service management. These CRDs define custom resources in several istio.io API groups, such as networking.istio.io and security.istio.io . The CRDs also include various resource kinds, such as AuthorizationPolicy , DestinationRule , and VirtualService , that administrators use to configure a service mesh. 1.3. About Istio deployment To deploy Istio, you must create two resources: Istio and IstioCNI . The Istio resource deploys and configures the Istio Control Plane. The IstioCNI resource deploys and configures the Istio Container Network Interface (CNI) plugin. You should create these resources in separate projects; therefore, you must create two projects as part of the Istio deployment process. You can use the OpenShift web console or the OpenShift CLI (oc) to create a project or a resource in your cluster. Note In the OpenShift Container Platform, a project is essentially a Kubernetes namespace with additional annotations, such as the range of user IDs that can be used in the project. Typically, the OpenShift Container Platform web console uses the term project, and the CLI uses the term namespace, but the terms are essentially synonymous. 1.3.1. Creating the Istio project using the web console The Service Mesh Operator deploys the Istio control plane to a project that you create. In this example, istio-system is the name of the project. Prerequisties The Red Hat OpenShift Service Mesh Operator must be installed. You are logged in to the OpenShift Container Platform web console as cluster-admin. Procedure In the OpenShift Container Platform web console, click Home Projects . Click Create Project . At the prompt, enter a name for the project in the Name field. For example, istio-system . The other fields provide supplementary information to the Istio resource definition and are optional. Click Create . The Service Mesh Operator deploys Istio to the project you specified. 1.3.2. Creating the Istio resource using the web console Create the Istio resource that will contain the YAML configuration file for your Istio deployment. The Red Hat OpenShift Service Mesh Operator uses information in the YAML file to create an instance of the Istio control plane. Prerequisties The Service Mesh Operator must be installed. You are logged in to the OpenShift Container Platform web console as cluster-admin. Procedure In the OpenShift Container Platform web console, click Operators Installed Operators . Select istio-system in the Project drop-down menu. Click the Service Mesh Operator. Click Istio . Click Create Istio . Select the istio-system project from the Namespace drop-down menu. Click Create . This action deploys the Istio control plane. When State: Healthy appears in the Status column, Istio is successfully deployed. 1.3.3. Creating the IstioCNI project using the web console The Service Mesh Operator deploys the Istio CNI plugin to a project that you create. In this example, istio-cni is the name of the project. Prerequisties The Red Hat OpenShift Service Mesh Operator must be installed. You are logged in to the OpenShift Container Platform web console as cluster-admin. Procedure In the OpenShift Container Platform web console, click Home Projects . Click Create Project . At the prompt, you must enter a name for the project in the Name field. For example, istio-cni . The other fields provide supplementary information and are optional. Click Create . 1.3.4. Creating the IstioCNI resource using the web console Create an Istio Container Network Interface (CNI) resource, which contains the configuration file for the Istio CNI plugin. The Service Mesh Operator uses the configuration specified by this resource to deploy the CNI pod. Prerequisties The Red Hat OpenShift Service Mesh Operator must be installed. You are logged in to the OpenShift Container Platform web console as cluster-admin. Procedure In the OpenShift Container Platform web console, click Operators Installed Operators . Select istio-cni in the Project drop-down menu. Click the Service Mesh Operator. Click IstioCNI . Click Create IstioCNI . Ensure that the name is default . Click Create . This action deploys the Istio CNI plugin. When State: Healthy appears in the Status column, the Istio CNI plugin is successfully deployed. 1.4. Scoping the Service Mesh with discovery selectors Service Mesh includes workloads that meet the following criteria: The control plane has discovered the workload. The workload has an Envoy proxy sidecar injected. By default, the control plane discovers workloads in all namespaces across the cluster, with the following results: Each proxy instance receives configuration for all namespaces, including workloads not enrolled in the mesh. Any workload with the appropriate pod or namespace injection label receives a proxy sidecar. In shared clusters, you might want to limit the scope of Service Mesh to only certain namespaces. This approach is especially useful if multiple service meshes run in the same cluster. 1.4.1. About discovery selectors With discovery selectors, the mesh administrator can control which namespaces the control plane can access. By using a Kubernetes label selector, the administrator sets the criteria for the namespaces visible to the control plane, excluding any namespaces that do not match the specified criteria. Note Istiod always opens a watch to OpenShift for all namespaces. However, discovery selectors ignore objects that are not selected very early in its processing, minimizing costs. The discoverySelectors field accepts an array of Kubernetes selectors, which apply to labels on namespaces. You can configure each selector for different use cases: Custom label names and values. For example, configure all namespaces with the label istio-discovery=enabled . A list of namespace labels by using set-based selectors with OR logic. For instance, configure namespaces with istio-discovery=enabled OR region=us-east1 . Inclusion and exclusion of namespaces. For example, configure namespaces with istio-discovery=enabled AND the label app=helloworld . Note Discovery selectors are not a security boundary. Istiod continues to have access to all namespaces even when you have configured the discoverySelector field. Additional resources Label selectors Resources that support set-based requirements 1.4.2. Scoping a Service Mesh by using discovery selectors If you know which namespaces to include in the Service Mesh, configure discoverySelectors during or after installation by adding the required selectors to the meshConfig.discoverySelectors section of the Istio resource. For example, configure Istio to discover only namespaces labeled istio-discovery=enabled . Prerequisites The OpenShift Service Mesh operator is installed. An Istio CNI resource is created. Procedure Add a label to the namespace containing the Istio control plane, for example, the istio-system system namespace. USD oc label namespace istio-system istio-discovery=enabled Modify the Istio control plane resource to include a discoverySelectors section with the same label. kind: Istio apiVersion: sailoperator.io/v1alpha1 metadata: name: default spec: namespace: istio-system values: meshConfig: discoverySelectors: - matchLabels: istio-discovery: enabled Apply the Istio CR: USD oc apply -f istio.yaml Ensure that all namespaces that will contain workloads that are to be part of the Service Mesh have both the discoverySelector label and, if needed, the appropriate Istio injection label. Note Discovery selectors help restrict the scope of a single Service Mesh and are essential for limiting the control plane scope when you deploy multiple Istio control planes in a single cluster. steps Deploying the Bookinfo application 1.5. About the Bookinfo application Installing the bookinfo example application consists of two main tasks: deploying the application and creating a gateway so the application is accessible outside the cluster. You can use the bookinfo application to explore service mesh features. Using the bookinfo application, you can easily confirm that requests from a web browser pass through the mesh and reach the application. 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, lists book details (ISBN, number of pages, and other information), and book reviews. The bookinfo application is exposed through the mesh, and the mesh configuration determines how the microservices comprising the application are used to serve requests. The review information comes from one of three services: reviews-v1 , reviews-v2 or reviews-v3 . If you deploy the bookinfo application without defining the reviews virtual service, then the mesh uses a round robin rule to route requests to a service. By deploying the reviews virtual service, you can specify a different behavior. For example, you can specify that if a user logs into the bookinfo application, then the mesh routes requests to the reviews-v2 service, and the application displays reviews with black stars. If a user does not log into the bookinfo application, then the mesh routes requests to the reviews-v3 service, and the application displays reviews with red stars. For more information, see Bookinfo Application in the upstream Istio documentation. 1.5.1. Deploying the Bookinfo application Prerequisites You have deployed a cluster on OpenShift Container Platform 4.15 or later. You are logged in to the OpenShift Container Platform web console as a user with the cluster-admin role. You have access to the OpenShift CLI (oc). You have installed the Red Hat OpenShift Service Mesh Operator, created the Istio resource, and the Operator has deployed Istio. You have created IstioCNI resource, and the Operator has deployed the necessary IstioCNI pods. Procedure In the OpenShift Container Platform web console, navigate to the Home Projects page. Click Create Project . Enter bookinfo in the Project name field. The Display name and Description fields provide supplementary information and are not required. Click Create . Apply the Istio discovery selector and injection label to the bookinfo namespace by entering the following command: USD oc label namespace bookinfo istio-discovery=enabled istio-injection=enabled Note In this example, the name of the Istio resource is default . If the Istio resource name is different, you must set the istio.io/rev label to the name of the Istio resource instead of adding the istio-injection=enabled label. Apply the bookinfo YAML file to deploy the bookinfo application by entering the following command: oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo Verification Verify that the bookinfo service is available by running the following command: USD oc get services -n bookinfo Example output NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE details ClusterIP 172.30.137.21 <none> 9080/TCP 44s productpage ClusterIP 172.30.2.246 <none> 9080/TCP 43s ratings ClusterIP 172.30.33.85 <none> 9080/TCP 44s reviews ClusterIP 172.30.175.88 <none> 9080/TCP 44s Verify that the bookinfo pods are available by running the following command: USD oc get pods -n bookinfo Example output NAME READY STATUS RESTARTS AGE details-v1-698d88b-km2jg 2/2 Running 0 66s productpage-v1-675fc69cf-cvxv9 2/2 Running 0 65s ratings-v1-6484c4d9bb-tpx7d 2/2 Running 0 65s reviews-v1-5b5d6494f4-wsrwp 2/2 Running 0 65s reviews-v2-5b667bcbf8-4lsfd 2/2 Running 0 65s reviews-v3-5b9bd44f4-44hr6 2/2 Running 0 65s When the Ready columns displays 2/2 , the proxy sidecar was successfully injected. Confirm that Running appears in the Status column for each pod. Verify that the bookinfo application is running by sending a request to the bookinfo page. Run the following command: USD oc exec "USD(oc get pod -l app=ratings -n bookinfo -o jsonpath='{.items[0].metadata.name}')" -c ratings -n bookinfo -- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>" 1.5.2. About accessing the Bookinfo application using a gateway The Red Hat OpenShift Service Mesh Operator does not deploy gateways. Gateways are not part of the control plane. As a security best-practice, Ingress and Egress gateways should be deployed in a different namespace than the namespace that contains the control plane. You can deploy gateways using either the Gateway API or the gateway injection method. 1.5.3. Accessing the Bookinfo application by using Istio gateway injection Gateway injection uses the same mechanisms as Istio sidecar injection to create a gateway from a Deployment resource that is paired with a Service resource. The Service resource can be made accessible from outside an OpenShift Container Platform cluster. Prerequisites You are logged in to the OpenShift Container Platform web console as cluster-admin . The Red Hat OpenShift Service Mesh Operator must be installed. The Istio resource must be deployed. Procedure Create the istio-ingressgateway deployment and service by running the following command: USD oc apply -n bookinfo -f ingress-gateway.yaml Note This example uses a sample ingress-gateway.yaml file that is available in the Istio community repository. Configure the bookinfo application to use the new gateway. Apply the gateway configuration by running the following command: USD oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/networking/bookinfo-gateway.yaml -n bookinfo Note To configure gateway injection with the bookinfo application, this example uses a sample gateway configuration file that must be applied in the namespace where the application is installed. Use a route to expose the gateway external to the cluster by running the following command: USD oc expose service istio-ingressgateway -n bookinfo Modify the YAML file to automatically scale the pod when ingress traffic increases. Example configuration apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: labels: istio: ingressgateway release: istio name: ingressgatewayhpa namespace: bookinfo spec: maxReplicas: 5 1 metrics: - resource: name: cpu target: averageUtilization: 80 type: Utilization type: Resource minReplicas: 2 scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: istio-ingressgateway 1 This example sets the the maximum replicas to 5 and the minimum replicas to 2 . It also creates another replica when utilization reaches 80%. Specify the minimum number of pods that must be running on the node. Example configuration apiVersion: policy/v1 kind: PodDisruptionBudget metadata: labels: istio: ingressgateway release: istio name: ingressgatewaypdb namespace: bookinfo spec: minAvailable: 1 1 selector: matchLabels: istio: ingressgateway 1 This example ensures one replica is running if a pod gets restarted on a new node. Obtain the gateway host name and the URL for the product page by running the following command: USD HOST=USD(oc get route istio-ingressgateway -n bookinfo -o jsonpath='{.spec.host}') Verify that the productpage is accessible from a web browser by running the following command: USD echo productpage URL: http://USDHOST/productpage 1.5.4. Accessing the Bookinfo application by using Gateway API The Kubernetes Gateway API deploys a gateway by creating a Gateway resource. In OpenShift Container Platform 4.15 and later versions. If you want your cluster to use the Gateway API CRDs, you must enable the CRDs because they are disabled by default. Note Red Hat provides support for using the Kubernetes Gateway API with Red Hat OpenShift Service Mesh. Red Hat does not provide support for the Kubernetes Gateway API custom resource definitions (CRDs). In this procedure, the use of community Gateway API CRDs is shown for demonstration purposes only. Prerequisites You are logged in to the OpenShift Container Platform web console as cluster-admin . The Red Hat OpenShift Service Mesh Operator must be installed. The Istio resource must be deployed. Procedure Enable the Gateway API CRDs: USD oc get crd gateways.gateway.networking.k8s.io &> /dev/null || { oc kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.0.0" | oc apply -f -; } Create and configure a gateway using a Gateway resource and HTTPRoute resource: USD oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/gateway-api/bookinfo-gateway.yaml -n bookinfo Note To configure a gateway with the bookinfo application by using the Gateway API, this example uses a sample gateway configuration file that must be applied in the namespace where the application is installed. Ensure that the Gateway API service is ready, and has an address allocated: USD oc wait --for=condition=programmed gtw bookinfo-gateway -n bookinfo Retrieve the host, port and gateway URL: USD export INGRESS_HOST=USD(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.status.addresses[0].value}') USD export INGRESS_PORT=USD(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.spec.listeners[?(@.name=="http")].port}') USD export GATEWAY_URL=USDINGRESS_HOST:USDINGRESS_PORT Obtain the gateway host name and the URL of the product page: USD echo "http://USD{GATEWAY_URL}/productpage" Verify that the productpage is accessible from a web browser. 1.6. Customizing Istio configuration The values field of the Istio custom resource definition, which was created when the control plane was deployed, can be used to customize Istio configuration using Istio's Helm configuration values. When you create this resource using the OpenShift Container Platform web console, it is pre-populated with configuration settings to enable Istio to run on OpenShift. Procedure Click Operators Installed Operators . Click Istio in the Provided APIs column. Click the Istio instance, named default , in the Name column. Click YAML to view the Istio configuration and make modifications. For a list of available configuration for the values field, refer to Istio's artifacthub chart documentation . Base parameters Istiod parameters Gateway parameters CNI parameters ZTunnel parameters Additional resources Service Mesh 3.0 Operator community documentation

Commands:
oc label namespace istio-system istio-discovery=enabled
kind: Istio apiVersion: sailoperator.io/v1alpha1 metadata: name: default spec: namespace: istio-system values: meshConfig: discoverySelectors: - matchLabels: istio-discovery: enabled
oc apply -f istio.yaml
oc label namespace bookinfo istio-discovery=enabled istio-injection=enabled
apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo
oc get services -n bookinfo
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE details ClusterIP 172.30.137.21 <none> 9080/TCP 44s productpage ClusterIP 172.30.2.246 <none> 9080/TCP 43s ratings ClusterIP 172.30.33.85 <none> 9080/TCP 44s reviews ClusterIP 172.30.175.88 <none> 9080/TCP 44s
oc get pods -n bookinfo
NAME READY STATUS RESTARTS AGE details-v1-698d88b-km2jg 2/2 Running 0 66s productpage-v1-675fc69cf-cvxv9 2/2 Running 0 65s ratings-v1-6484c4d9bb-tpx7d 2/2 Running 0 65s reviews-v1-5b5d6494f4-wsrwp 2/2 Running 0 65s reviews-v2-5b667bcbf8-4lsfd 2/2 Running 0 65s reviews-v3-5b9bd44f4-44hr6 2/2 Running 0 65s
oc exec "USD(oc get pod -l app=ratings -n bookinfo -o jsonpath='{.items[0].metadata.name}')" -c ratings -n bookinfo -- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>"
oc apply -n bookinfo -f ingress-gateway.yaml
oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/networking/bookinfo-gateway.yaml -n bookinfo
oc expose service istio-ingressgateway -n bookinfo
apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: labels: istio: ingressgateway release: istio name: ingressgatewayhpa namespace: bookinfo spec: maxReplicas: 5 1 metrics: - resource: name: cpu target: averageUtilization: 80 type: Utilization type: Resource minReplicas: 2 scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: istio-ingressgateway
apiVersion: policy/v1 kind: PodDisruptionBudget metadata: labels: istio: ingressgateway release: istio name: ingressgatewaypdb namespace: bookinfo spec: minAvailable: 1 1 selector: matchLabels: istio: ingressgateway
HOST=USD(oc get route istio-ingressgateway -n bookinfo -o jsonpath='{.spec.host}')
echo productpage URL: http://USDHOST/productpage
oc get crd gateways.gateway.networking.k8s.io &> /dev/null || { oc kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.0.0" | oc apply -f -; }
oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/gateway-api/bookinfo-gateway.yaml -n bookinfo
oc wait --for=condition=programmed gtw bookinfo-gateway -n bookinfo
export INGRESS_HOST=USD(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.status.addresses[0].value}') export INGRESS_PORT=USD(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.spec.listeners[?(@.name=="http")].port}') export GATEWAY_URL=USDINGRESS_HOST:USDINGRESS_PORT
echo "http://USD{GATEWAY_URL}/productpage"