Chapter 2. Before migrating

If you are a current Red Hat OpenShift Service Mesh user, there are several important differences you need to understand between OpenShift Service Mesh 2 and OpenShift Service Mesh 3 before you migrate, including the following:

You must be using OpenShift Service Mesh 2.6 to migrate to OpenShift Service Mesh 3.

Red Hat OpenShift Service Mesh 3 is a major update with a feature set closer to the "Istio project". Whereas OpenShift Service Mesh 2 was based on the midstream Maistra project, OpenShift Service Mesh 3 is based directly on Istio. This means OpenShift Service Mesh 3 is managed using a different, simplified Operator and provides greater support for the latest stable features of Istio.

This alignment with the Istio project along with lessons learned in the first two major releases of OpenShift Service Mesh have resulted in the following changes:

Red Hat OpenShift Service Mesh 3 uses the following two new resources:

$ oc explain istios.spec.values

A significant change in Red Hat OpenShift Service Mesh 3 is that the Operator no longer installs and manages observability components such as Prometheus and Grafana with the Istio control plane. It also no longer installs and manages Red Hat OpenShift distributed tracing platform components such as distributed tracing platform (Tempo) and Red Hat OpenShift distributed tracing data collection (previously Jaeger and Elasticsearch), or Kiali.

The OpenShift Service Mesh 3 Operator limits its scope to Istio-related resources, with observability components supported and managed by the independent Operators that make up Red Hat OpenShift Observability, such as the following:

Kiali and the OpenShift Service Mesh Console (OSSMC) plugin are still supported with the Kiali Operator provided by Red Hat.

This simplification greatly reduces the footprint and complexity of OpenShift Service Mesh 3, while providing better, production-grade support for observability through Red Hat OpenShift Observability components.

In OpenShift Service Mesh 2.4, a cluster-wide mode was introduced to allow a mesh to be cluster-scoped, with the option to limit the mesh by using an Istio feature called discoverySelectors.

Using discoverySelectors limits the Istio control plane’s visibility to a set of namespaces defined with a label selector. This aligned with how community Istio worked, and allowed Istio to manage cluster-level resources. For more information, see "Labels and Selectors".

OpenShift Service Mesh 3 makes all meshes cluster-wide by default. This change means that Istio control planes are all cluster-scoped resources and the resources ServiceMeshMemberRoll and ServiceMeshMember are no longer present, with control planes watching, or discovering, the entire cluster by default. The control plane’s discovery of namespaces can be limited using the discoverySelectors feature.

Red Hat OpenShift Service Mesh 2 supported using pod annotations and labels to configure sidecar injection and there was no need to indicate which control plane a workload belonged to.

With OpenShift Service Mesh 3, even though the Istio control plane discovers a namespace, the workloads present in that namespace still require sidecar proxies to be included as workloads in the service mesh, and to be able to use Istio’s many features.

In OpenShift Service Mesh 3, sidecar injection works the same way as it does for Istio, with pod or namespace labels used to trigger sidecar injection. However, it might be necessary to include a label that indicates which control plane the workload belongs to.

When an Istio resource has the name default and InPlace upgrades are used, there is a single IstioRevision with the name default and the label istio-injection=enabled for sidecar injection.

However, an IstioRevision resource is required to have a different name in the following cases:

If there are running multiple control plane instances, or you chose the RevisionBased update strategy during your OpenShift Service Mesh 3 installation, then an IstioRevision resource is required to have a different name than default. When that happens, it is necessary to use a label that indicates which control plane revision the workloads belong to by specifying istio.io/rev=<istiorevision_name>.

These labels can be applied at the workload or namespace level.

You can inspect available revisions by running the following command:

$ oc get istiorevision

Red Hat OpenShift Service Mesh 3 supports multiple service meshes in the same cluster, but in a different manner than in OpenShift Service Mesh 2. A cluster administrator must create multiple Istio instances and then configure discoverySelectors appropriately to ensure that there is no overlap between mesh namespaces.

As Istio resources are cluster-scoped, they must have unique names to represent unique meshes within the same cluster. The OpenShift Service Mesh 3 Operator uses this unique name to create a resource called IstioRevision with a name in the format of {Istio name} or {Istio name}-{Istio version}.

Each instance of IstioRevision is responsible for managing a single control plane. Workloads are assigned to a specific control plane by using Istio’s revision labels of the format istio.io/rev={IstioRevision name}. The name with the version identifier becomes important to support canary-style control plane upgrades.

In Istio, gateways are used to manage traffic entering (ingress) and exiting (egress) the mesh. Red Hat OpenShift Service Mesh 2 deployed and managed an ingress gateway and an egress gateway with the Service Mesh control plane. Both an ingress gateway and an egress gateway were configured using the ServiceMeshControlPlane resource.

The OpenShift Service Mesh 3 Operator does not create or manage gateways.

Instead, gateways in OpenShift Service Mesh 3 are created and managed independent of the Operator and control plane by using gateway injection or the Kubernetes Gateway API. This provides greater flexibility and ensures that gateways can be fully customized and managed as part of a Red Hat OpenShift GitOps pipeline. This allows the gateways to be deployed and managed alongside their applications with the same lifecycle.

This change was made for two reasons:

Gateways might continue to be deployed onto nodes or namespaces independent of applications. For example, a centralized gateway node. Istio gateways also remain eligible to be deployed on OpenShift Container Platform infrastructure nodes.

An OpenShift Route resource allows an application to be exposed with a public URL by using OpenShift Container Platform Ingress Operator for managing HAProxy based Ingress controllers.

Red Hat OpenShift Service Mesh 2 used Istio OpenShift Routing (IOR) that automatically created and managed OpenShift routes for Istio gateways. While this was convenient, as the Operator managed these routes for you, it also caused confusion around ownership as many Route resources are managed by administrators. Istio OpenShift Routing also lacked the ability to configure an independent Route resource, created unnecessary routes, and exhibited unpredictable behavior during updates.

Thus, in OpenShift Service Mesh 3, when a Route is required to expose an Istio gateway, you must create and manage it manually. You can also expose an Istio gateway through a Kubernetes service of type LoadBalancer if a route is not required.

Red Hat OpenShift Service Mesh 3 addresses the risks of traditional in-place updates by providing revision-based update strategies that allow for incremental workload transitions and simplified rollbacks.

OpenShift Service Mesh 3 retains support for simple in-place style updates, and adds support for canary-style updates of the Istio control plane by using Istio’s revision feature.

The Istio resource manages Istio revision labels by using the IstioRevision resource. When the Istio resource’s updateStrategy type is set to RevisionBased, it creates Istio revision labels by using the Istio resource’s name combined with the Istio version, for example mymesh-v1-21-2.

During an updates, a new IstioRevision deploys the new Istio control plane with an updated revision label, for example mymesh-v1-22-0. Workloads can then be migrated between control planes by using the revision label on namespaces or workloads, for example istio.io/rev=mymesh-v1-22-0.

Setting your updateStrategy to RevisionBased also has implications for integrations, such as the cert-manager tool, and gateways.

Red Hat OpenShift Service Mesh 2 supported one form of multi-cluster, federation, which was introduced in OpenShift Service Mesh 2.1. Each cluster maintained its own independent control plane in this topology, with services only shared between those meshes on an as-needed basis.

Communication between federated meshes is through Istio gateways, so there was no need for Service Mesh control planes to watch remote Kubernetes control planes, as is the case with Istio’s multi-cluster service mesh topologies. Federation is ideal where service meshes are loosely coupled, such as those managed by different administrative teams.

OpenShift Service Mesh 3 introduces support for the following Istio multi-cluster topologies as well:

These topologies effectively stretch a single, unified service mesh across multiple clusters, which is ideal when all clusters involved are managed by the same administrative team. Istio’s multi-cluster topologies are also ideal for implementing high-availability or failover use cases across a commonly managed set of applications.

Red Hat OpenShift Service Mesh 1 and 2 did not include support for Istioctl, the command line utility for the Istio project that includes many diagnostic and debugging utilities. OpenShift Service Mesh 3 introduces support for Istioctl for select commands.

The following commands are supported in OpenShift Service Mesh 3:

Installation and management of Istio is only supported by the OpenShift Service Mesh 3 Operator.

By default, Red Hat OpenShift Service Mesh 2 created Kubernetes NetworkPolicy resources with the following behavior:

OpenShift Service Mesh 3 does not create these policies. Instead, you must configure the level of isolation required for your environment. Istio provides fine grained access control of service mesh workloads through Authorization Policies. For more information, see "Authorization Policies".

In Red Hat OpenShift Service Mesh 2, you created the ServiceMeshControlPlane resource, and enabled mTLS strict mode by setting spec.security.dataPlane.mtls to true.

You were able to set the minimum and maximum TLS protocol versions by setting the spec.security.controlPlane.tls.minProtocolVersion or spec.security.controlPlane.tls.maxProtocolVersion in your ServiceMeshControlPlane resource.

In OpenShift Service Mesh 3, the Istio resource replaces the ServiceMeshControlPlane resource and does not include these settings.

To enable mTLS strict mode in OpenShift Service Mesh 3, you must apply the corresponding PeerAuthentication and DestinationRule resources.

In OpenShift Service Mesh 3, you can enable the minimum TLS protocol by setting spec.meshConfig.tlsDefaults.minProtocolVersion in your Istio resource. For more information, see "Istio Workload Minimum TLS Version Configuration".

In OpenShift Service Mesh 2 and OpenShift Service Mesh 3, auto mTLS remains enabled by default.

To maintain access to external services when migrating to Red Hat OpenShift Service Mesh 3.0, you must explicitly enable DNS capture in the proxy metadata settings.

This is required for any ServiceEntry resources that rely on DNS resolution. Failure to enable this feature results in application errors such as Name or service not known.

OpenShift Service Mesh 2.6 enabled DNS capture by default to support federation, which did not align with the upstream Istio project. OpenShift Service Mesh 3.0 removes this default configuration and aligns with the upstream project’s multicluster topologies.

To configure DNS capture in OpenShift Service Mesh 3.0, set the ISTIO_META_DNS_AUTO_ALLOCATE and ISTIO_META_DNS_CAPTURE fields to true in the spec.values.meshConfig.defaultConfig.proxyMetadata path of your Istio resource.

Verify that your environment meets the following requirements, version dependencies, and operator installations necessary to begin the migration from OpenShift Service Mesh 2 to OpenShift Service Mesh 3.

To prepare for your migration to OpenShift Service Mesh 3, you must disable legacy add-ons in your OpenShift Service Mesh 2 ServiceMeshControlPlane resource and reconfigure replacements for the features that those add-ons provided.

Automatic route creation, also known as Istio OpenShift Routing (IOR), is a deprecated feature that is disabled by default for any ServiceMeshControlPlane resource created using OpenShift Service Mesh 2.5 and later.

To move from OpenShift Service Mesh 2 to OpenShift Service Mesh 3, you need to migrate from IOR to explicitly-managed routes.

If you already moved to explicitly-managed routes in OpenShift Service Mesh 2, then continue to gateway injection.

Gateways were controlled by the ServiceMeshControlPlane (SMCP) resource in OpenShift Service Mesh 2. The OpenShift Service Mesh 3 control plane does not manage gateways so you must migrate from SMCP-Defined gateways to gateway injection.

If you do not want your network policies in place during your migration:

If you want your network policies in place during your migration:

Grafana is not supported in OpenShift Service Mesh 3, and must be disabled in your OpenShift Service Mesh 2 ServiceMeshControlPlane.

After you have completed the premigration procedures, your OpenShift Service Mesh 2 resources might be similar to the following examples:

apiVersion: maistra.io/v2
kind: ServiceMeshControlPlane
metadata:
  name: basic
  namespace: istio-system
spec:
  version: v2.6
  security:
    manageNetworkPolicy: false
  addons:
    grafana:
      enabled: false
    kiali:
      enabled: false
    prometheus:
      enabled: false
  meshConfig:
    extensionProviders:
      - name: prometheus
        prometheus: {}
      - name: otel
        opentelemetry:
          port: 4317
          service: otel-collector.istio-system.svc.cluster.local
  gateways:
    enabled: false
    openshiftRoute:
      enabled: false
  mode: MultiTenant
  tracing:
    type: None

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: mesh-default
  namespace: istio-system
spec:
  metrics:
    - providers:
        - name: prometheus
  tracing:
    - providers:
        - name: otel

apiVersion: kiali.io/v1alpha1
kind: Kiali
metadata:
  name: kiali
  namespace: istio-system
spec:
  version: default
  external_services:
    prometheus:
      auth:
        type: bearer
        use_kiali_token: true
      thanos_proxy:
        enabled: true
      url: https://thanos-querier.openshift-monitoring.svc.cluster.local:9091
    tracing:
      enabled: true
      provider: tempo
      use_grpc: false
      internal_url: http://tempo-sample-query-frontend.tempo:3200
      external_url: https://tempo-sample-query-frontend-tempo.apps-crc.testing
    grafana:
      enabled: false

Run the following command to find your deployment model:

oc get smcp <smcp-name> -n <smcp-namespace> -o jsonpath='{.spec.mode}'

If you are not using the cert-manager tool with your deployment, you are ready to migrate your deployment. Refer to the following migration guides based on your deployment model:

If you are unsure, you can check if you are using the cert-manager tool with your deployment.

You must check if your deployment uses the cert-manager tool. If you are using the cert-manager tool with OpenShift Service Mesh 2, you must perform additional configurations before you can start migrating your deployments and workloads.

You can set up network policies to use during your migration.

Kiali Operator provided by Red Hat with Red Hat OpenShift Service Mesh 3 introduces the following changes:

These changes reflect evolving capabilities and configuration standards of Kiali within OpenShift Service Mesh 3.