Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Cluster-wide migration guide

4.1. Cluster-wide migration guide
Copy link

This guide is for users who are running a cluster-wide deployment of Red Hat OpenShift Service Mesh 2.6.14 and are migrating to OpenShift Service Mesh 3.0.

Important

You must complete the premigration checklists before you start migrating your deployment.

During the migration process, two cluster-wide control planes run in the same cluster while the data plane namespaces are gradually migrated to the Red Hat OpenShift Service Mesh 3.0 installation. One control plane is associated with the Red Hat OpenShift Service Mesh 2.6.14 installation and the other is associated with the OpenShift Service Mesh 3.0 installation. You must carefully plan the migration steps to avoid possible conflicts between the two control planes.

Important

You must complete the premigration checklists before you start migrating your deployment.

4.1.1.1. Root certificate
Copy link

During the migration, both control planes must share a root certificate. To share a root certificate between both control planes, you install the 3.0 control plane into the same namespace as 2.6 control plane. The migration procedures show how to verify that the root certificate is shared.

4.1.1.2. Discovery selectors and namespace access
Copy link

Both control planes must have access to all namespaces in the mesh. During the migration, some proxies are controlled by the 3.0 control plane while other proxies remain controlled by the 2.6 control plane. To ensure that mesh communication works during the migration, both control planes must detect the same set of services. Service discovery is provided by istiod component, which runs in the control plane namespace.

In the OpenShift Service Mesh 3.0 installation, you can control how Istio discovers services by using discovery selectors. When you use discovery selectors, ensure that the discoverySelectors expression that is defined in the OpenShift Service Mesh 3.0 Istio resource match the namespaces that comprise the OpenShift Service Mesh 2.6 mesh. You might have to add additional labels to the OpenShift Service Mesh 2.6 application namespaces to ensure that they are captured in the OpenShift Service Mesh 3.0 installation. For more information, see "Scoping the service mesh with DiscoverySelectors".

Note

In OpenShift Service Mesh 2.6 installations, the maistra.io/member-of label is automatically created. This label cannot be used because it is automatically removed during the migration process.

4.1.1.3. Network policies
Copy link

By default, OpenShift Service Mesh 2.6 manages network policies that block traffic to the 3.0 control plane.

For both control planes, during the migration ensure that network policies do not block traffic between the following entities:

  • The control plane and the data plane namespaces
  • The data plane namespaces and the control plane
  • The data plane namespaces themselves

In the premigration checklist, you are instructed to disable network policies. However, you can manually re-create them. Manually created network policies must allow traffic for both control planes. When a data plane namespace is migrated to 3.0, the maistra.io/member-of label is automatically removed. Do not use this label in network policies. For more information, see "Set up network policies to use during migration".

Note

In OpenShift Service Mesh 2.6 installations, the maistra.io/member-of label is automatically created. This label cannot be used because it is automatically removed during the migration process.

Incorrectly configured network policies can disrupt mesh traffic. When you run the migration, be careful when you create network policies to prevent traffic disruption. For more information, see "Set up network policies to use during migration".

4.1.1.4. Sidecar injection
Copy link

If both control planes try to perform sidecar injection, the proxy will not start and the migration cannot be completed. To ensure that only one control plane performs sidecar injection during the migration, use injection labels. For more information, see "Installing the Sidecar".

Note

During the migration, you must disable the 2.6 injector. Use the maistra.io/ignore-namespace: "true" label to prevent the 2.6 control plane from injecting a proxy in the namespace.

4.1.1.5. Label selection
Copy link

For OpenShift Service Mesh 3.0, you must decide if you want to use the istio.io/rev label or the istio-injection label to configure sidecar injection. For more information, see "About sidecar injection".

In the OpenShift Service Mesh 2.6 installation, the member selection configuration in the ServiceMeshMemberRoll resource can impact how injection labels are used in the OpenShift Service Mesh 3.0 installation.

By default, in a 2.6 installation, the spec.memberSelectors field in the ServiceMeshMemberRoll resource is configured to match the istio-injection=enabled label and all of the data plane namespaces in a 2.6 installation have the istio-injection=enabled label applied. If you are using the default 2.6 installation settings, you can keep using that label or switch to the istio.io/rev label for the 3.0 installation.

If the spec.memberSelectors field in the ServiceMeshMemberRoll resource is not configured to match the istio-injection=enabled label and the 2.6 data plane namespace uses a custom label, you must add the istio.io/rev label or the istio-injection label during the migration. The custom labels defined in the spec.memberSelectors parameter of the ServiceMeshMemberRoll resource have no effect on sidecar injection in the OpenShift Service Mesh 3 installation and cannot be used.

If projects in the 2.6 installation were added to the mesh by manually creating the ServiceMeshMember resource, you must add the istio.io/rev or istio-injection label to the project namespaces during the migration.

4.1.2. Cluster-wide migration methods
Copy link

You can migrate the control plane from Red Hat OpenShift Service Mesh 2.6.14 to OpenShift Service Mesh 3.0 by using one of the following methods:

  • Applying the istio.io/rev label
  • Applying the istio-injection=enabled label

  • Performing a simple migration by using the istio-injection=enabled label

    Note

    The simple migration method might introduce traffic disruptions.

To select the best migration method for your OpenShift Service Mesh installation, you must understand the difference between the istio.io/rev and istio-injection labels. Read through all the migration methods before choosing the one that best fits your needs.

You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the istio.io/rev label.

The bookinfo example application is being used for demonstration purposes with a minimal example for the Istio resource. For more information on configuration differences between the OpenShift Service Mesh 2 ServiceMeshControlPlane resource and the OpenShift Service Mesh 3 Istio resource, see "Configuration fields mapping between Service Mesh 2 and Service Mesh 3".

You can follow these same steps with your own workloads.

Prerequisites

  • You have deployed OpenShift Container Platform 4.14 or later.
  • You have logged in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  • You have completed the premigration checklists.
  • You have the OpenShift Service Mesh 2.6.14 Operator installed.
  • You have the OpenShift Service Mesh 3 Operator installed.
  • You have created an IstioCNI resource.
  • You have installed the istioctl tool.
  • You are running a cluster-wide Service Mesh control plane resource.
  • You have installed the bookinfo application.

Procedure

  1. Identify the namespaces that contain a 2.6 control plane by running the following command: 

    $ oc get smcp -A

    Example output: 

    NAMESPACE      NAME                   READY   STATUS            PROFILES      VERSION       AGE
istio-system   install-istio-system   6/6     ComponentsReady   ["default"]   2.6.6         115m

  2. Create a YAML file named ossm-3.yaml that creates the Istio resource for the 3.0 installation in the same namespace as the ServiceMeshControlPlane resource for the 2.6 installation.

    Note

    In the following example configuration, the Istio control plane has access to all namespaces on the cluster. If you want limit the namespaces the control plan has access to, you must define discovery selectors. All data plane namespaces that you plan to migrate from version 2.6 must be matched.

    You can see the following example configuration for reference: 

    apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: ossm-3
spec:
  updateStrategy:
    type: RevisionBased
  namespace: istio-system
  version: v1.24.6
  values:
    meshConfig:
      extensionProviders:
        - name: prometheus
          prometheus: {}
        - name: otel
          opentelemetry:
            port: 4317
            service: otel-collector.opentelemetrycollector-3.svc.cluster.local
    • metadata.name The name, updateStrategy and version fields specify how the IstioRevision resource name is created. For more information, see "Identifying the revision name".
    • spec.namespace The 3.0 and 2.6 control planes must run in the same namespace.
    • spec.values If you are migrating metrics and tracing, update the extensionProviders fields according to your tracing and metrics configurations.

  3. Apply the YAML file by running the following command: 

    $ oc apply -f ossm-3.yaml

  4. Verify that the new istiod resource uses the existing root certificate by running the following command: 

    $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret'

    Example output: 

    2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret

Now you can migrate your workloads from the OpenShift Service Mesh 2.6 control plane to the OpenShift Service Mesh 3.0 control plane.

Revision tags are not used in this example for simplicity. When migrating large meshes, you can use revision tags to avoid re-labeling all namespaces during future version 3 updates.

Note

You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways".

Procedure

  1. Find the current IstioRevision for your OpenShift Service Mesh 3.0 control plane by running the following command: 

    $ oc get istios

    Example output: 

    NAME             REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
ossm-3           1           1       0        ossm-3-v1-24-3    Healthy   v1.24.3   30s

  2. Copy the value in the ACTIVE REVISION column to use as your istio.io/rev label in the next step.

    Note

    The naming format of your revisions depends on which upgrade strategy you choose for your Istio instance.

  3. Update the injection labels on the dataplane namespace by running the following command: 

    $ oc label ns bookinfo istio.io/rev=ossm-3-v1-24-3 maistra.io/ignore-namespace="true" istio-injection- --overwrite=true

    Running the command performs the following actions:

    1. Removes the istio-injection label: This label prevents the 3.0 control plane from injecting the proxy. The istio-injection label takes precedence over istio.io/rev label.
    2. Adds the istio.io/rev=ossm-3-v1-24-3 label: This label ensures that any newly created or restarted pods in the namespace connect to the OpenShift Service Mesh 3.0 proxy.

    3. Adds the maistra.io/ignore-namespace: "true" label: This label disables sidecar injection for OpenShift Service Mesh 2.6 proxies in the namespace. With the label applied, OpenShift Service Mesh 2.6 stops injecting proxies in this namespace, and any new proxies are injected by OpenShift Service Mesh 3.0. Without this label, the OpenShift Service Mesh 2.6 injection webhook tries to inject the pod and the injected sidecar proxy refuses to start since it will have both the OpenShift Service Mesh 2.6 and the OpenShift Service Mesh 3.0 Container Network Interface(CNI) annotations.

      Note

      Once you apply the maistra.io/ignore-namespace label, any new pod that gets created in the namespace connects to the OpenShift Service Mesh 3.0 proxy. Workloads can still communicate with each other regardless of which control plane they are connected to.

  4. Restart the workloads by using one of the following options:

    1. To restart all the workloads at once so that the new pods are injected with the OpenShift Service Mesh 3.0 proxy, run the following command: 

      $ oc rollout restart deployments -n bookinfo

    2. To restart each workload individually, run the following command for each workload: 

      $ oc rollout restart deployments productpage-v1 -n bookinfo

  5. Wait for the productpage application to restart by running the following command: 

    $ oc rollout status deployment productpage-v1 -n bookinfo

Verification

  1. Ensure that expected workloads are managed by the new control plane by running the following command: 

    $ istioctl ps -n bookinfo

    Example output: 

    $ istioctl ps -n bookinfo
NAME                                          CLUSTER        CDS             LDS             EDS             RDS             ECDS         ISTIOD                                           VERSION
details-v1-7f46897b-d497c.bookinfo            Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
productpage-v1-74bfbd4d65-vsxqm.bookinfo      Kubernetes     SYNCED (4s)     SYNCED (4s)     SYNCED (3s)     SYNCED (4s)     IGNORED      istiod-ossm-3-v1-24-3-797bb4d78f-xpchx           1.24.3
ratings-v1-559b64556-c5ppg.bookinfo           Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v1-847fb7c54d-qxt5d.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v2-5c7ff5b77b-8jbhd.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v3-5c5d764c9b-rrx8w.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8

    The previous output shows that the productpage-v1 deployment is the only deployment that restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between services still works.

  2. If the 2.6 installation has additional data plane namespaces, migrate the next namespace now.

    Note

    Do not remove the maistra.io/ignore-namespace="true" label until the 2.6 control plane is uninstalled.

Next steps

If you are using gateways, you must migrate them before you complete the migration process.

  • See: "Migrating gateways"

If you are not using gateways, and have verified your cluster-wide migration, you can proceed to complete the migration and remove OpenShift Service Mesh 2 resources.

  • See: "Completing the Migration"

You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the istio.io/rev label.

The bookinfo example application is being used for demonstration purposes with a minimal example for the Istio resource. For more information on configuration differences between the OpenShift Service Mesh 2 ServiceMeshControlPlane resource and the OpenShift Service Mesh 3 Istio resource, see "Configuration fields mapping between Service Mesh 2 and Service Mesh 3".

You can follow these same steps with your own workloads.

Prerequisites

  • You have deployed OpenShift Container Platform 4.14 or later.
  • You have logged in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  • You have completed the premigration checklists.
  • You have the OpenShift Service Mesh 2.6.14 Operator installed.
  • You have the OpenShift Service Mesh 3 Operator installed.
  • You have created an IstioCNI resource.
  • You have installed the istioctl tool.
  • You are using the cert-manager and istio-csr tools in a cluster-wide deployment.
  • Your OpenShift Service Mesh 2.6.14 ServiceMeshControlPlane resource is configured with the cert-manager tool.
  • You have installed the bookinfo application.

Procedure

  1. Confirm that your OpenShift Service Mesh 2 ServiceMeshControlPlane resource is configured with the cert-manager tool.

    You can see the following example configuration for reference: 

    apiVersion: maistra.io/v2
kind: ServiceMeshControlPlane
metadata:
  name: basic
  namespace: istio-system
spec:
  ...
  security:
    certificateAuthority:
      cert-manager:
        address: cert-manager-istio-csr.istio-system.svc:443
      type: cert-manager
    dataPlane:
      mtls: true
    identity:
      type: ThirdParty
    manageNetworkPolicy: false

  2. Update the istio-csr deployment to include your OpenShift Service Mesh 3 control plane by running the following command: 

      helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
      --install \
      --reuse-values \
      --namespace istio-system \
      --wait \
      --set "app.istio.revisions={basic,ossm-3-v1-24-3}"

    where:

    app.istio.revisions
    This field must include your OpenShift Service Mesh 3.0 control plane revision before you create your Istio resource so that proxies can properly communicate with the OpenShift Service Mesh 3.0 control plane.

  3. Identify the namespaces that contain a 2.6 control plane by running the following command: 

    $ oc get smcp -A

    Example output: 

    NAMESPACE      NAME                   READY   STATUS            PROFILES      VERSION       AGE
istio-system   install-istio-system   6/6     ComponentsReady   ["default"]   2.6.6         115m

  4. Create a YAML file named ossm-3.yaml that creates the Istio resource for the 3.0 installation in the same namespace as the ServiceMeshControlPlane resource for the 2.6 installation.

    Note

    In the following example configuration, the Istio control plane has access to all namespaces on the cluster. If you want limit the namespaces the control plan has access to, you must define discovery selectors. All data plane namespaces that you plan to migrate from version 2.6 must be matched.

    You can see the following example configuration for reference: 

    apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: ossm-3
spec:
  updateStrategy:
    type: RevisionBased
  namespace: istio-system
  version: v1.24.6
  values:
    meshConfig:
      extensionProviders:
        - name: prometheus
          prometheus: {}
        - name: otel
          opentelemetry:
            port: 4317
            service: otel-collector.opentelemetrycollector-3.svc.cluster.local
    • metadata.name The name, updateStrategy and version fields specify how the IstioRevision resource name is created. For more information, see "Identifying the revision name".
    • spec.namespace The 3.0 and 2.6 control planes must run in the same namespace.
    • spec.values If you are migrating metrics and tracing, update the extensionProviders fields according to your tracing and metrics configurations.

  5. Apply the YAML file by running the following command: 

    $ oc apply -f ossm-3.yaml

  6. Verify that the new istiod resource uses the existing root certificate by running the following command: 

    $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret'

    Example output: 

    2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret

Now you can migrate your workloads from the OpenShift Service Mesh 2.6 control plane to the OpenShift Service Mesh 3.0 control plane.

Revision tags are not used in this example for simplicity. When migrating large meshes, you can use revision tags to avoid re-labeling all namespaces during future version 3 updates.

Note

You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways".

Procedure

  1. Find the current IstioRevision for your OpenShift Service Mesh 3.0 control plane by running the following command: 

    $ oc get istios

    Example output: 

    NAME             REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
ossm-3           1           1       0        ossm-3-v1-24-3    Healthy   v1.24.3   30s

  2. Copy the value in the ACTIVE REVISION column to use as your istio.io/rev label in the next step.

    Note

    The naming format of your revisions depends on which upgrade strategy you choose for your Istio instance.

  3. Update the injection labels on the dataplane namespace by running the following command: 

    $ oc label ns bookinfo istio.io/rev=ossm-3-v1-24-3 maistra.io/ignore-namespace="true" istio-injection- --overwrite=true

    Running the command performs the following actions:

    1. Removes the istio-injection label: This label prevents the 3.0 control plane from injecting the proxy. The istio-injection label takes precedence over istio.io/rev label.
    2. Adds the istio.io/rev=ossm-3-v1-24-3 label: This label ensures that any newly created or restarted pods in the namespace connect to the OpenShift Service Mesh 3.0 proxy.

    3. Adds the maistra.io/ignore-namespace: "true" label: This label disables sidecar injection for OpenShift Service Mesh 2.6 proxies in the namespace. With the label applied, OpenShift Service Mesh 2.6 stops injecting proxies in this namespace, and any new proxies are injected by OpenShift Service Mesh 3.0. Without this label, the OpenShift Service Mesh 2.6 injection webhook tries to inject the pod and the injected sidecar proxy refuses to start since it will have both the OpenShift Service Mesh 2.6 and the OpenShift Service Mesh 3.0 Container Network Interface(CNI) annotations.

      Note

      Once you apply the maistra.io/ignore-namespace label, any new pod that gets created in the namespace connects to the OpenShift Service Mesh 3.0 proxy. Workloads can still communicate with each other regardless of which control plane they are connected to.

  4. Restart the workloads by using one of the following options:

    1. To restart all the workloads at once so that the new pods are injected with the OpenShift Service Mesh 3.0 proxy, run the following command: 

      $ oc rollout restart deployments -n bookinfo

    2. To restart each workload individually, run the following command for each workload: 

      $ oc rollout restart deployments productpage-v1 -n bookinfo

  5. Wait for the productpage application to restart by running the following command: 

    $ oc rollout status deployment productpage-v1 -n bookinfo

Verification

  1. Ensure that expected workloads are managed by the new control plane by running the following command: 

    $ istioctl ps -n bookinfo

    Example output: 

    $ istioctl ps -n bookinfo
NAME                                          CLUSTER        CDS             LDS             EDS             RDS             ECDS         ISTIOD                                           VERSION
details-v1-7f46897b-d497c.bookinfo            Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
productpage-v1-74bfbd4d65-vsxqm.bookinfo      Kubernetes     SYNCED (4s)     SYNCED (4s)     SYNCED (3s)     SYNCED (4s)     IGNORED      istiod-ossm-3-v1-24-3-797bb4d78f-xpchx           1.24.3
ratings-v1-559b64556-c5ppg.bookinfo           Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v1-847fb7c54d-qxt5d.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v2-5c7ff5b77b-8jbhd.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v3-5c5d764c9b-rrx8w.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8

    The previous output shows that the productpage-v1 deployment is the only deployment that restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between services still works.

  2. If the 2.6 installation has additional data plane namespaces, migrate the next namespace now.

    Note

    Do not remove the maistra.io/ignore-namespace="true" label until the 2.6 control plane is uninstalled.

Next steps

If you are using gateways, you must migrate them before you complete the migration process.

  • See: "Migrating gateways"

If you are not using gateways, and have verified your cluster-wide migration, you can proceed to complete the migration and remove OpenShift Service Mesh 2 resources.

  • See: "Completing the Migration"

You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the istio-injection=enabled label and the default revision tag.

You must re-label all of the data plane namespaces. However, it is safe to restart any of the workloads at any point during the migration process.

The bookinfo application is used as an example for the Istio resource. For more information about configuration differences between the OpenShift Service Mesh 2 ServiceMeshControlPlane resource and the OpenShift Service Mesh 3 Istio resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping".

Prerequisites

  • You have deployed OpenShift Container Platform 4.14 or later.
  • You have logged in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  • You have completed the premigration checklists.
  • You have the OpenShift Service Mesh 2.6.14 Operator installed.
  • You have the OpenShift Service Mesh 3 Operator installed.
  • You have created an IstioCNI resource.
  • You have installed the istioctl tool.
  • You are running a cluster-wide Service Mesh control plane resource.
  • You have installed the bookinfo application.

Procedure

  1. Identify the namespaces that contain a 2.6 control plane by running the following command: 

    $ oc get smcp -A

    Example output: 

    NAMESPACE      NAME                   READY   STATUS            PROFILES      VERSION   AGE
istio-system   install-istio-system   6/6     ComponentsReady   ["default"]   2.6.6     115m

  2. Create a YAML file named ossm-3.yaml. This procedure creates the Istio resource for the 3.0 installation in the same namespace as the ServiceMeshControlPlane resource for the 2.6 installation.

    Note

    In the following example configuration, the Istio control plane has access to all namespaces on the cluster. If you want to limit the namespaces the control plan has access to, you must define discovery selectors. You must match all the data plane namespaces that you plan to migrate from version 2.6.

    You can see the following example configuration for reference: 

    apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: ossm-3
spec:
  updateStrategy:
    type: RevisionBased
  namespace: istio-system
  version: v1.24.3
  values:
    meshConfig:
      extensionProviders:
        - name: prometheus
          prometheus: {}
        - name: otel
          opentelemetry:
            port: 4317
            service: otel-collector.opentelemetrycollector-3.svc.cluster.local
    • metadata.name specifies the name of the IstioRevision resource. The updateStrategy and version fields specify how the resource is updated. For more information, see "Identifying the revision name".
    • spec.namespace specifies the namespace where the 3.0 and 2.6 control planes must run.

    • spec.values specifies the configuration values for the 3.0 control plane. If you are migrating metrics and tracing, update the extensionProviders fields according to your tracing and metrics configurations.

      Note

      To prevent the OpenShift Service Mesh 3.0 control plane from injecting proxies in the namespaces that have the istio-injection=enabled label applied and are still managed by OpenShift Service Mesh 2.6 control plane, do not use the default name for the Istio resource, and do not create the default revision tag in the following steps. You create the default revision tag later in this procedure.

  3. Apply the YAML file by running the following command: 

    $ oc apply -f ossm-3.yaml

Verification

  1. Verify that the new istiod resource uses the existing root certificate by running the following command: 

    $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret'

    Example output: 

    2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret

Now you can migrate your workloads from the OpenShift Service Mesh 2.6 control plane to the OpenShift Service Mesh 3.0 control plane.

Note

You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways".

Procedure

  1. Find the current IstioRevision resource for your OpenShift Service Mesh 3.0 control plane by running the following command: 

    $ oc get istios

    Example output: 

    NAME             REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
ossm-3           1           1       0        ossm-3-v1-24-3    Healthy   v1.24.3   30s

  2. Copy the ACTIVE REVISION value to use as your istio.io/rev label in the next step.

    Note

    The naming format of your revisions depends on which upgrade strategy you choose for your Istio instance.

  3. Update the injection labels on the data plane namespace by running the following command: 

    $ oc label ns bookinfo istio.io/rev=ossm-3-v1-24-3 maistra.io/ignore-namespace="true" istio-injection- --overwrite=true

    The oc label command performs the following actions:

    1. Removes the istio-injection label: This label prevents the 3.0 control plane from injecting the proxy. The istio-injection label takes precedence over the istio.io/rev label. You must temporarily remove the istio-injection=enabled because you cannot create the default IstioRevisionTag tag yet. Leaving the istio-injection=enabled label applied would prevent the 3.0 control plane from performing proxy injection.
    2. Adds the istio.io/rev=ossm-3-v1-24-3 label: This label ensures that any newly created or restarted pods in the namespace connect to the OpenShift Service Mesh 3.0 proxy.

    3. Adds the maistra.io/ignore-namespace: "true" label: This label disables sidecar injection for OpenShift Service Mesh 2.6 proxies in the namespace. With the label applied, OpenShift Service Mesh 2.6 stops injecting proxies in this namespace, and any new proxies are injected by OpenShift Service Mesh 3.0. Without this label, the OpenShift Service Mesh 2.6 injection webhook tries to inject the pod and the injected sidecar proxy refuses to start since it will has both the OpenShift Service Mesh 2.6 and the OpenShift Service Mesh 3.0 Container Network Interface(CNI) annotations.

      Note

      After you apply the maistra.io/ignore-namespace label, any new pod that gets created in the namespace connects to the OpenShift Service Mesh 3.0 proxy. Workloads can still communicate with each other regardless of which control plane they are connected to.

  4. Restart the workloads by using one of the following options:

    1. To restart all the workloads at the same time so that the new pods are injected with the OpenShift Service Mesh 3.0 proxy, run the following command: 

      $ oc rollout restart deployments -n bookinfo

    2. To restart each workload individually, run the following command for each workload: 

      $ oc rollout restart deployments productpage-v1 -n bookinfo

  5. Wait for the productpage application to restart by running the following command: 

    $ oc rollout status deployment productpage-v1 -n bookinfo

Verification

  1. Verify that the new control plane manages the expected workloads by running the following command: 

    $ istioctl ps -n bookinfo

    Example output: 

    NAME                                          CLUSTER        CDS             LDS             EDS             RDS             ECDS         ISTIOD                                           VERSION
details-v1-7f46897b-d497c.bookinfo            Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
productpage-v1-74bfbd4d65-vsxqm.bookinfo      Kubernetes     SYNCED (4s)     SYNCED (4s)     SYNCED (3s)     SYNCED (4s)     IGNORED      istiod-ossm-3-v1-24-3-797bb4d78f-xpchx           1.24.3
ratings-v1-559b64556-c5ppg.bookinfo           Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v1-847fb7c54d-qxt5d.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v2-5c7ff5b77b-8jbhd.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v3-5c5d764c9b-rrx8w.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8

    The output shows that the productpage-v1 deployment is the only deployment that has been restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between the services still works.

  2. If the 2.6 installation has additional namespaces, migrate the next namespace now.

    Note

    Remove the maistra.io/ignore-namespace="true" label only after the 2.6 control plane has been uninstalled.

Next steps

If you are using gateways, you must migrate them before you complete the migration process.

  • See: "Migrating gateways"

If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and relabel namespaces.

You can create the default revision tag and relabel the namespaces after you have completed the OpenShift Service Mesh 2 to OpenShift Service Mesh 3 cluster-wide migration process by using the Istio injection label.

The bookinfo application is used as an example.

Prerequisites

  • You have completed the OpenShift Service Mesh 2 to OpenShift Service Mesh 3 cluster-wide migration process by using Istio injection label.

Procedure

  1. Create a YAML file called rev-tag.yaml that defines the IstioRevisionTag resource:

    Example IstioRevisionTag resource: 

    apiVersion: sailoperator.io/v1
kind: IstioRevisionTag
metadata:
  name: default
spec:
  targetRef:
    kind: IstioRevision
    name: ossm-3-v1-24-3

  2. Apply the YAML file by running the following command: 

    $ oc apply -f rev-tag.yaml

  3. Verify the status of the IstioRevisionTag resource by running the following command: 

    $ oc get istiorevisiontags

    Example output: 

    NNAME      STATUS                    IN USE   REVISION        AGE
default    NotReferencedByAnything   False    ossm-3-v1-24-3  18s

  4. Add the istio-injection=enabled label to the bookinfo namespace, and remove the istio.io/rev label by running the following command: 

    $ oc label ns bookinfo istio-injection=enabled istio.io/rev-
    Note

    Remove the maistra.io/ignore-namespace="true" label only after the 2.6 control plane has been uninstalled.

  5. Restart the workloads by running the following command: 

    $ oc rollout restart deployments -n bookinfo
    Note

    Repeat steps 4 and 5 for each namespace you are migrating.

Verification

  1. Verify that the IstioRevisionTag resource is in use by running the following command: 

    $ oc get istiorevisiontags

    Example output: 

    NAME      STATUS    IN USE   REVISION        AGE
default   Healthy   True     ossm-3-v1-24-3  28s

  2. Ensure that expected workloads are managed by the new control plane by running the following command: 

    $ istioctl ps -n bookinfo

    Example output: 

    NAME                                         CLUSTER        CDS              LDS              EDS             RDS              ECDS        ISTIOD                                     VERSION
details-v1-79dfbd6fff-t5lzm.bookinfo         Kubernetes     SYNCED (57s)     SYNCED (57s)     SYNCED (3s)     SYNCED (57s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
details-v1-7cb48d8bb-6rjq8.bookinfo          Kubernetes     SYNCED (3s)      SYNCED (3s)      SYNCED (3s)     SYNCED (3s)      IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
productpage-v1-7d9cdf655d-cqk48.bookinfo     Kubernetes     SYNCED (10s)     SYNCED (10s)     SYNCED (3s)     SYNCED (10s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
ratings-v1-5b67b59fcb-w4whk.bookinfo         Kubernetes     SYNCED (18s)     SYNCED (18s)     SYNCED (3s)     SYNCED (18s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
reviews-v1-585fc84dbb-fvm2h.bookinfo         Kubernetes     SYNCED (11s)     SYNCED (11s)     SYNCED (3s)     SYNCED (11s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
reviews-v2-65cb66b45c-6ggp9.bookinfo         Kubernetes     SYNCED (57s)     SYNCED (57s)     SYNCED (3s)     SYNCED (57s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
reviews-v2-698b86b848-v92xq.bookinfo         Kubernetes     SYNCED (3s)      SYNCED (3s)      SYNCED (3s)     SYNCED (3s)      IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
reviews-v3-6cbc49c8c8-v4jck.bookinfo         Kubernetes     SYNCED (11s)     SYNCED (11s)     SYNCED (3s)     SYNCED (11s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3

Next steps

You can proceed to complete the migration and remove OpenShift Service Mesh 2 resources.

  • See: "Completing the Migration"
Important

Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways.

You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the istio-injection=enabled label and the default revision tag.

You must re-label all of the data plane namespaces. However, it is safe to restart any of the workloads at any point during the migration process.

The bookinfo application is used as an example for the Istio resource. For more information about configuration differences between the OpenShift Service Mesh 2 ServiceMeshControlPlane resource and the OpenShift Service Mesh 3 Istio resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping".

Prerequisites

  • You have deployed OpenShift Container Platform 4.14 or later.
  • You have logged in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  • You have completed the premigration checklists.
  • You have the OpenShift Service Mesh 2.6.14 Operator installed.
  • You have the OpenShift Service Mesh 3 Operator installed.
  • You have created an IstioCNI resource.
  • You have installed the istioctl tool.
  • You are using the cert-manager and istio-csr tools in a cluster-wide deployment.
  • Your OpenShift Service Mesh 2.6.14 ServiceMeshControlPlane resource is configured with the cert-manager tool
  • You have installed the bookinfo application.

Procedure

  1. Confirm that your OpenShift Service Mesh 2 ServiceMeshControlPlane resource is configured with the cert-manager tool.

    You can see the following example configuration for reference: 

    apiVersion: maistra.io/v2
kind: ServiceMeshControlPlane
metadata:
  name: basic
  namespace: istio-system
spec:
  ...
  security:
    certificateAuthority:
      cert-manager:
        address: cert-manager-istio-csr.istio-system.svc:443
      type: cert-manager
    dataPlane:
      mtls: true
    identity:
      type: ThirdParty
    manageNetworkPolicy: false

  2. Update the istio-csr deployment to include your OpenShift Service Mesh 3 control plane by running the following command: 

      helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
      --install \
      --reuse-values \
      --namespace istio-system \
      --wait \
      --set "app.istio.revisions={basic,ossm-3-v1-24-3}"

    where:

    app.istio.revisions
    This field must include your OpenShift Service Mesh 3.0 control plane revision before you create your Istio resource so that proxies can properly communicate with the OpenShift Service Mesh 3.0 control plane.

  3. Identify the namespaces that contain a 2.6 control plane by running the following command: 

    $ oc get smcp -A

    Example output: 

    NAMESPACE      NAME                   READY   STATUS            PROFILES      VERSION   AGE
istio-system   install-istio-system   6/6     ComponentsReady   ["default"]   2.6.6     115m

  4. Create a YAML file named ossm-3.yaml. This procedure creates the Istio resource for the 3.0 installation in the same namespace as the ServiceMeshControlPlane resource for the 2.6 installation.

    Note

    In the following example configuration, the Istio control plane has access to all namespaces on the cluster. If you want to limit the namespaces the control plan has access to, you must define discovery selectors. You must match all the data plane namespaces that you plan to migrate from version 2.6.

    You can see the following example configuration for reference: 

    apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: ossm-3
spec:
  updateStrategy:
    type: RevisionBased
  namespace: istio-system
  version: v1.24.3
  values:
    meshConfig:
      extensionProviders:
        - name: prometheus
          prometheus: {}
        - name: otel
          opentelemetry:
            port: 4317
            service: otel-collector.opentelemetrycollector-3.svc.cluster.local
    • metadata.name specifies the name of the IstioRevision resource. The updateStrategy and version fields specify how the resource is updated. For more information, see "Identifying the revision name".
    • spec.namespace specifies the namespace where the 3.0 and 2.6 control planes must run.

    • spec.values specifies the configuration values for the 3.0 control plane. If you are migrating metrics and tracing, update the extensionProviders fields according to your tracing and metrics configurations.

      Note

      To prevent the OpenShift Service Mesh 3.0 control plane from injecting proxies in the namespaces that have the istio-injection=enabled label applied and are still managed by OpenShift Service Mesh 2.6 control plane, do not use the default name for the Istio resource, and do not create the default revision tag in the following steps. You create the default revision tag later in this procedure.

  5. Apply the YAML file by running the following command: 

    $ oc apply -f ossm-3.yaml

Verification

  1. Verify that the new istiod resource uses the existing root certificate by running the following command: 

    $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret'

    Example output: 

    2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret

Now you can migrate your workloads from the OpenShift Service Mesh 2.6 control plane to the OpenShift Service Mesh 3.0 control plane.

Note

You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways".

Procedure

  1. Find the current IstioRevision resource for your OpenShift Service Mesh 3.0 control plane by running the following command: 

    $ oc get istios

    Example output: 

    NAME             REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
ossm-3           1           1       0        ossm-3-v1-24-3    Healthy   v1.24.3   30s

  2. Copy the ACTIVE REVISION value to use as your istio.io/rev label in the next step.

    Note

    The naming format of your revisions depends on which upgrade strategy you choose for your Istio instance.

  3. Update the injection labels on the data plane namespace by running the following command: 

    $ oc label ns bookinfo istio.io/rev=ossm-3-v1-24-3 maistra.io/ignore-namespace="true" istio-injection- --overwrite=true

    The oc label command performs the following actions:

    1. Removes the istio-injection label: This label prevents the 3.0 control plane from injecting the proxy. The istio-injection label takes precedence over the istio.io/rev label. You must temporarily remove the istio-injection=enabled because you cannot create the default IstioRevisionTag tag yet. Leaving the istio-injection=enabled label applied would prevent the 3.0 control plane from performing proxy injection.
    2. Adds the istio.io/rev=ossm-3-v1-24-3 label: This label ensures that any newly created or restarted pods in the namespace connect to the OpenShift Service Mesh 3.0 proxy.

    3. Adds the maistra.io/ignore-namespace: "true" label: This label disables sidecar injection for OpenShift Service Mesh 2.6 proxies in the namespace. With the label applied, OpenShift Service Mesh 2.6 stops injecting proxies in this namespace, and any new proxies are injected by OpenShift Service Mesh 3.0. Without this label, the OpenShift Service Mesh 2.6 injection webhook tries to inject the pod and the injected sidecar proxy refuses to start since it will has both the OpenShift Service Mesh 2.6 and the OpenShift Service Mesh 3.0 Container Network Interface(CNI) annotations.

      Note

      After you apply the maistra.io/ignore-namespace label, any new pod that gets created in the namespace connects to the OpenShift Service Mesh 3.0 proxy. Workloads can still communicate with each other regardless of which control plane they are connected to.

  4. Restart the workloads by using one of the following options:

    1. To restart all the workloads at the same time so that the new pods are injected with the OpenShift Service Mesh 3.0 proxy, run the following command: 

      $ oc rollout restart deployments -n bookinfo

    2. To restart each workload individually, run the following command for each workload: 

      $ oc rollout restart deployments productpage-v1 -n bookinfo

  5. Wait for the productpage application to restart by running the following command: 

    $ oc rollout status deployment productpage-v1 -n bookinfo

Verification

  1. Verify that the new control plane manages the expected workloads by running the following command: 

    $ istioctl ps -n bookinfo

    Example output: 

    NAME                                          CLUSTER        CDS             LDS             EDS             RDS             ECDS         ISTIOD                                           VERSION
details-v1-7f46897b-d497c.bookinfo            Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
productpage-v1-74bfbd4d65-vsxqm.bookinfo      Kubernetes     SYNCED (4s)     SYNCED (4s)     SYNCED (3s)     SYNCED (4s)     IGNORED      istiod-ossm-3-v1-24-3-797bb4d78f-xpchx           1.24.3
ratings-v1-559b64556-c5ppg.bookinfo           Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v1-847fb7c54d-qxt5d.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v2-5c7ff5b77b-8jbhd.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v3-5c5d764c9b-rrx8w.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8

    The output shows that the productpage-v1 deployment is the only deployment that has been restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between the services still works.

  2. If the 2.6 installation has additional namespaces, migrate the next namespace now.

    Note

    Remove the maistra.io/ignore-namespace="true" label only after the 2.6 control plane has been uninstalled.

Next steps

If you are using gateways, you must migrate them before you complete the migration process.

  • See: "Migrating gateways"

If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and relabel namespaces.

Important

Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways.

You can create the default revision tag and relabel the namespaces after you have completed the OpenShift Service Mesh 2 to OpenShift Service Mesh 3 cluster-wide migration process by using the Istio injection label.

The bookinfo application is used as an example.

Prerequisites

  • You have completed the OpenShift Service Mesh 2 to OpenShift Service Mesh 3 cluster-wide migration process by using Istio injection label.

Procedure

  1. Create a YAML file called rev-tag.yaml that defines the IstioRevisionTag resource:

    Example IstioRevisionTag resource: 

    apiVersion: sailoperator.io/v1
kind: IstioRevisionTag
metadata:
  name: default
spec:
  targetRef:
    kind: IstioRevision
    name: ossm-3-v1-24-3

  2. Apply the YAML file by running the following command: 

    $ oc apply -f rev-tag.yaml

  3. Verify the status of the IstioRevisionTag resource by running the following command: 

    $ oc get istiorevisiontags

    Example output: 

    NNAME      STATUS                    IN USE   REVISION        AGE
default    NotReferencedByAnything   False    ossm-3-v1-24-3  18s

  4. Add the istio-injection=enabled label to the bookinfo namespace, and remove the istio.io/rev label by running the following command: 

    $ oc label ns bookinfo istio-injection=enabled istio.io/rev-
    Note

    Remove the maistra.io/ignore-namespace="true" label only after the 2.6 control plane has been uninstalled.

  5. Restart the workloads by running the following command: 

    $ oc rollout restart deployments -n bookinfo
    Note

    Repeat steps 4 and 5 for each namespace you are migrating.

Verification

  1. Verify that the IstioRevisionTag resource is in use by running the following command: 

    $ oc get istiorevisiontags

    Example output: 

    NAME      STATUS    IN USE   REVISION        AGE
default   Healthy   True     ossm-3-v1-24-3  28s

  2. Ensure that expected workloads are managed by the new control plane by running the following command: 

    $ istioctl ps -n bookinfo

    Example output: 

    NAME                                         CLUSTER        CDS              LDS              EDS             RDS              ECDS        ISTIOD                                     VERSION
details-v1-79dfbd6fff-t5lzm.bookinfo         Kubernetes     SYNCED (57s)     SYNCED (57s)     SYNCED (3s)     SYNCED (57s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
details-v1-7cb48d8bb-6rjq8.bookinfo          Kubernetes     SYNCED (3s)      SYNCED (3s)      SYNCED (3s)     SYNCED (3s)      IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
productpage-v1-7d9cdf655d-cqk48.bookinfo     Kubernetes     SYNCED (10s)     SYNCED (10s)     SYNCED (3s)     SYNCED (10s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
ratings-v1-5b67b59fcb-w4whk.bookinfo         Kubernetes     SYNCED (18s)     SYNCED (18s)     SYNCED (3s)     SYNCED (18s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
reviews-v1-585fc84dbb-fvm2h.bookinfo         Kubernetes     SYNCED (11s)     SYNCED (11s)     SYNCED (3s)     SYNCED (11s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
reviews-v2-65cb66b45c-6ggp9.bookinfo         Kubernetes     SYNCED (57s)     SYNCED (57s)     SYNCED (3s)     SYNCED (57s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
reviews-v2-698b86b848-v92xq.bookinfo         Kubernetes     SYNCED (3s)      SYNCED (3s)      SYNCED (3s)     SYNCED (3s)      IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3
reviews-v3-6cbc49c8c8-v4jck.bookinfo         Kubernetes     SYNCED (11s)     SYNCED (11s)     SYNCED (3s)     SYNCED (11s)     IGNORED     istiod-ossm-3-v1-24-3-6595bf8695-s8ktn     1.24.3

You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the simple migration method. In an OpenShift Service Mesh 2.6.14 installation, if the istio-injection=enabled label is already applied to the data plane namespaces, the simple migration method is the easiest way to migrate from the OpenShift Service Mesh 2 installation to the OpenShift Service Mesh 3 installation.

The simple migration method should not be used in production environments.

Note

Using the simple migration method to migrate from OpenShift Service Mesh 2 to OpenShift Service Mesh 3 might result in traffic disruption to the services running on a mesh. There are two methods to perform the cluster-wide migration without disrupting traffic. See "Migrating a cluster-wide deployment by using the istio injection label" or "Migrating a cluster-wide deployment by using the Istio revision label" for more information.

The bookinfo application is used as an example for the Istio resource. For more information about configuration differences between the OpenShift Service Mesh 2 ServiceMeshControlPlane resource and the OpenShift Service Mesh 3 Istio resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping."

Prerequisites

  • You have deployed OpenShift Container Platform 4.14 or later.
  • You have logged in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  • You have completed the premigration checklists.
  • You have the OpenShift Service Mesh 2.6.14 Operator installed.
  • You have the OpenShift Service Mesh 3 Operator installed.
  • You have created an IstioCNI resource.
  • You have installed the istioctl tool.
  • You are running a cluster-wide Service Mesh control plane resource.
  • You have installed the bookinfo application.

Procedure

  1. Identify the namespaces that contain a 2.6 control plane by running the following command: 

    $ oc get smcp -A

    Example output: 

    NAMESPACE      NAME                   READY   STATUS            PROFILES      VERSION   AGE
istio-system   install-istio-system   6/6     ComponentsReady   ["default"]   2.6.6     115m

  2. Create a YAML file named ossm-3.yaml. This procedure creates the Istio resource for the 3.0 installation in the same namespace as the ServiceMeshControlPlane resource for the 2.6 installation.

    Note

    In the following example configuration, the Istio control plane has access to all namespaces on the cluster. If you want to limit the namespaces the control plane has access to, you must define discovery selectors. You must match all the data plane namespaces that you plan to migrate from version 2.6.

    You can see the following example configuration for reference: 

    apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  updateStrategy:
    type: InPlace
  namespace: istio-system
  version: v1.24.3
  values:
    meshConfig:
      extensionProviders:
        - name: prometheus
          prometheus: {}
        - name: otel
          opentelemetry:
            port: 4317
            service: otel-collector.opentelemetrycollector-3.svc.cluster.local
    • metadata.name specifies the name, updateStrategy and version fields specify how the IstioRevision resource name is created. For more information, see "Identifying the revision name."
    • spec.namespace specifies the namespace in which the 3.0 and 2.6 control planes must run.

    • spec.values specifies the values for the Istio resource. If you are migrating metrics and tracing, update the extensionProviders fields according to your tracing and metrics configurations.

      Note

      If the Istio resource is named default, and the installation uses the InPlace update strategy, you can use the istio-injection=enabled label without creating the IstioRevisionTag tag. If you use a different name for the Istio resource or you use the RevisionBased update strategy, you must configure the default IstioRevisionTag tag. For more information, see "Creating the default revision tag and relabeling the namespaces."

  3. Apply the YAML file by running the following command: 

    $ oc apply -f ossm-3.yaml
    Note

    After you apply the YAML file, any time the workloads are restarted, both the OpenShift Service Mesh 2.6 and the OpenShift Service Mesh 3.0 control planes will try to inject side cars to all pods in namespaces that have the istio-injection=enabled label applied and to all pods that have the sidecar.istio.io/inject="true" label applied. This causes a traffic disruption. To prevent traffic disruption, restart the workloads only after the maistra.io/ignore-namespace: "true" label is added.

Verification

  1. Verify that the new istiod resource uses the existing root certificate by running the following command: 

    $ oc logs deployments/istiod -n istio-system | grep 'Load signing key and cert from existing secret'

    Example output: 

    2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret

After migrating a cluster-wide deployment, you can migrate your workloads from the OpenShift Service Mesh 2.6 control plane to the OpenShift Service Mesh 3.0 control plane.

Note

You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways."

Procedure

  1. Add the maistra.io/ignore-namespace: "true" label to the data plane namespace by running the following command: 

    $ oc label ns bookinfo maistra.io/ignore-namespace="true"

    The maistra.io/ignore-namespace: "true" label disables sidecar injection for OpenShift Service Mesh 2.6 proxies in the namespace. With the label applied, OpenShift Service Mesh 2.6 stops injecting proxies in this namespace, and any new proxies are injected by OpenShift Service Mesh 3.0. Without this label, the OpenShift Service Mesh 2.6 injection webhook tries to inject the pod and the injected sidecar proxy refuses to start since it has both the OpenShift Service Mesh 2.6 and the OpenShift Service Mesh 3.0 Container Network Interface(CNI) annotations.

    Note

    After you apply the maistra.io/ignore-namespace label, any new pod that gets created or restarted in the namespace connects to the OpenShift Service Mesh 3.0 proxy. Workloads can still communicate with each other regardless of which control plane they are connected to.

  2. Restart the workloads by using one of the following options:

    1. To restart all the workloads at the same time so that the new pods are injected with the OpenShift Service Mesh 3.0 proxy, run the following command: 

      $ oc rollout restart deployments -n bookinfo

    2. To restart each workload individually, run the following command for each workload: 

      $ oc rollout restart deployments productpage-v1 -n bookinfo

  3. Wait for the productpage application to restart by running the following command: 

    $ oc rollout status deployment productpage-v1 -n bookinfo

Verification

  1. Verify that the new control plane manages the expected workloads by running the following command: 

    $ istioctl ps -n bookinfo

    Example output: 

    NAME                                          CLUSTER        CDS             LDS             EDS             RDS             ECDS         ISTIOD                                           VERSION
details-v1-7f46897b-d497c.bookinfo            Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
productpage-v1-74bfbd4d65-vsxqm.bookinfo      Kubernetes     SYNCED (4s)     SYNCED (4s)     SYNCED (3s)     SYNCED (4s)     IGNORED      istiod-797bb4d78f-xpchx           1.24.3
ratings-v1-559b64556-c5ppg.bookinfo           Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v1-847fb7c54d-qxt5d.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v2-5c7ff5b77b-8jbhd.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8
reviews-v3-5c5d764c9b-rrx8w.bookinfo          Kubernetes     SYNCED          SYNCED          SYNCED          SYNCED          NOT SENT     istiod-install-istio-system-866b57d668-6lpcr     1.20.8

    The output shows that the productpage-v1 deployment is the only deployment that has been restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between the services still works.

  2. If the 2.6 installation has additional namespaces, migrate the next namespace now.

    Note

    Remove the maistra.io/ignore-namespace="true" label only after the 2.6 control plane has been uninstalled.

Next steps

If you are using gateways, you must migrate them before you complete the migration process.

  • See: "Migrating gateways"

If you are not using gateways, you can complete your migration.

  • See: "Completing the Migration"
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top