1. Documentation
×

Installing OpenShift Service Mesh

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.

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"

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

  1. In the OpenShift Container Platform web console, navigate to the Operators → OperatorHub page.

  2. Search for the Red Hat OpenShift Service Mesh 3 Operator.

  3. Locate the Service Mesh Operator, and click to select it.

  4. When the prompt that discusses the community operator appears, click Continue.

  5. Verify the Service Mesh Operator is version 3.0, and click Install.

  6. Use the default installation settings presented, and click Install to continue.

  7. Click Operators → Installed Operators to verify that the Service Mesh Operator is installed. Succeeded should appear in the Status column.

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.

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.

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.

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

  1. In the OpenShift Container Platform web console, click Home → Projects.

  2. Click Create Project.

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

  4. Click Create. The Service Mesh Operator deploys Istio to the project you specified.

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

  1. In the OpenShift Container Platform web console, click Operators → Installed Operators.

  2. Select istio-system in the Project drop-down menu.

  3. Click the Service Mesh Operator.

  4. Click Istio.

  5. Click Create Istio.

  6. Select the istio-system project from the Namespace drop-down menu.

  7. Click Create. This action deploys the Istio control plane.

    When State: Healthy appears in the Status column, Istio is successfully deployed.

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

  1. In the OpenShift Container Platform web console, click Home → Projects.

  2. Click Create Project.

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

  4. Click Create.

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

  1. In the OpenShift Container Platform web console, click Operators → Installed Operators.

  2. Select istio-cni in the Project drop-down menu.

  3. Click the Service Mesh Operator.

  4. Click IstioCNI.

  5. Click Create IstioCNI.

  6. Ensure that the name is default.

  7. Click Create. This action deploys the Istio CNI plugin.

    When State: Healthy appears in the Status column, the Istio CNI plugin is successfully deployed.

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.

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.

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.

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

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

  1. Add a label to the namespace containing the Istio control plane, for example, the istio-system system namespace.

    $ oc label namespace istio-system istio-discovery=enabled

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

  3. Apply the Istio CR:

    $ oc apply -f istio.yaml

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

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

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.

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

  1. In the OpenShift Container Platform web console, navigate to the Home → Projects page.

  2. Click Create Project.

  3. Enter bookinfo in the Project name field.

    The Display name and Description fields provide supplementary information and are not required.

  4. Click Create.

  5. Apply the Istio discovery selector and injection label to the bookinfo namespace by entering the following command:

    $ oc label namespace bookinfo istio-discovery=enabled istio-injection=enabled

    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.

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

  1. Verify that the bookinfo service is available by running the following command:

    $ 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

  2. Verify that the bookinfo pods are available by running the following command:

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

  3. Verify that the bookinfo application is running by sending a request to the bookinfo page. Run the following command:

    $ oc exec "$(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>"

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.

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.

Prerequisties

  • 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

  1. Create the istio-ingressgateway deployment and service by running the following command at the CLI:

    $ oc apply -n bookinfo -f ingress-gateway.yaml

    This example uses a sample ingress-gateway.yaml file that is available in the Istio community repository.

  2. Configure the bookinfo application to use the new gateway by applying the gateway configuration:

    $ oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/networking/bookinfo-gateway.yaml -n bookinfo

    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.

  3. Use a route to expose the gateway external to the cluster:

    $ oc expose service istio-ingressgateway -n bookinfo

  4. Automatically scale the pod when ingress traffic increases. This example sets the minimum replicas to 2 and the maximum replicas to 5. It also creates another replica when utilization reaches 80%.

    apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  labels:
    istio: ingressgateway
    release: istio
  name: ingressgatewayhpa
  namespace: istio-ingress
spec:
  maxReplicas: 5
  metrics:
  - resource:
      name: cpu
      target:
        averageUtilization: 80
        type: Utilization
    type: Resource
  minReplicas: 2
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: istio-ingressgateway

  5. Specify the minimum number of pods that must be running on the node. This example ensures one replica is running if a pod gets restarted on a new node.

    apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  labels:
    istio: ingressgateway
    release: istio
  name: ingressgatewaypdb
  namespace: istio-ingress
spec:
  minAvailable: 1
  selector:
    matchLabels:
      istio: ingressgateway

  6. Obtain the gateway host name and the URL for the product page:

    $ HOST=$(oc get route istio-ingressgateway -n bookinfo -o jsonpath='{.spec.host}')
$ echo productpage URL: http://$HOST/productpage

  7. Verify that the productpage is accessible from a web browser.

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.

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.

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

  1. Enable the Gateway API CRDs:

    $ 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 -; }

  2. Create and configure a gateway using a Gateway resource and HTTPRoute resource:

    $ oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/bookinfo/gateway-api/bookinfo-gateway.yaml -n bookinfo

    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.

  3. Ensure that the Gateway API service is ready, and has an address allocated:

    $ oc wait --for=condition=programmed gtw bookinfo-gateway -n bookinfo

  4. Retrieve the host, port and gateway URL:

    $ export INGRESS_HOST=$(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.status.addresses[0].value}')
$ export INGRESS_PORT=$(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')
$ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT

  5. Obtain the gateway host name and the URL of the product page:

    $ echo "http://${GATEWAY_URL}/productpage"

  6. Verify that the productpage is accessible from a web browser.

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

  1. Click Operators → Installed Operators.

  2. Click Istio in the Provided APIs column.

  3. Click the Istio instance, named default, in the Name column.

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

Additional resources