Migrating from Service Mesh 2 to Service Mesh 3

Procedure

1. Use one of the following ways to check if you are using the cert-manager tool with your deployment:

   1. Inspect your ServiceMeshControlPlane resource to verify that the spec.security.certificateAuthority.type parameter is set to cert-manager:

      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. Run the following command to verify that the spec.security.certificateAuthority.type parameter is set to cert-manager:

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

      Example output

      cert-manager

Procedure

1. Label namespaces by running the following command:

   $ oc label namespace <app_namespace> service-mesh=enabled

   Note

   Use a label scoped specifically to your mesh that you can reuse for discovery selectors.

2. Create your network policies by using the following NetworkPolicy example configurations:

   Example of an Istiod network policy in a mesh namespace

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: istiod-basic
     namespace: istio-system
   spec:
     ingress:
       - {}
     podSelector:
       matchLabels:
         app: istiod
         istio.io/rev: basic
     policyTypes:
       - Ingress

   Example of an expose route policy in a mesh namespace

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: expose-route-basic
     namespace: istio-system
   spec:
     podSelector:
       matchLabels:
         maistra.io/expose-route: "true"
     ingress:
       - from:
           - namespaceSelector:
               matchLabels:
                 network.openshift.io/policy-group: ingress
     policyTypes:
       - Ingress

   Example of a default mesh network policy in a mesh namespace

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: istio-mesh
     namespace: istio-system
   spec:
     ingress:
       - from:
           - namespaceSelector:
               matchLabels:
                 service-mesh: enabled
     podSelector: {}
     policyTypes:
       - Ingress

   Example expose route network policy in the bookinfo namespace

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: istio-expose-route
     namespace: bookinfo
   spec:
     podSelector:
       matchLabels:
         maistra.io/expose-route: "true"
     ingress:
       - from:
           - namespaceSelector:
               matchLabels:
                 network.openshift.io/policy-group: ingress
     policyTypes:
       - Ingress

   Example mesh network policy in the bookinfo namespace

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: istio-mesh
     namespace: bookinfo
   spec:
     ingress:
       - from:
           - namespaceSelector:
               matchLabels:
                 service-mesh: enabled
     podSelector: {}
     policyTypes:
       - Ingress

   Example expose route network policy in the bookinfo2 namespace

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: istio-expose-route
     namespace: bookinfo2
   spec:
     podSelector:
       matchLabels:
         maistra.io/expose-route: "true"
     ingress:
       - from:
           - namespaceSelector:
               matchLabels:
                 network.openshift.io/policy-group: ingress
     policyTypes:

   Example mesh network policy in the bookinfo2 namespace

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: istio-mesh
     namespace: bookinfo2
   spec:
     ingress:
       - from:
           - namespaceSelector:
               matchLabels:
                 service-mesh: enabled
     podSelector: {}
     policyTypes:
       - Ingress

3. Disable network policies in OpenShift Service Mesh 2 by setting the spec.security.manageNetworkPolicy field to false in your ServiceMeshControlPlane resource.

   Note

   Setting the spec.security.manageNetworkPolicy field to false in your ServiceMeshControlPlane resource removes the network policies created by default in OpenShift Service Mesh 2.

4. Find your current active revision by running the following command:

   $ oc get istios <istio_name>

   Example output

   NAME             REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
   istio-tenant-a   1           1       0        istio-tenant-a    Healthy   v1.24.3   30s

5. Copy the active revision name from the output to use for your istio.io/rev label in your second Istiod network policy for OpenShift Service Mesh 3.

6. Create a second Istiod network policy for OpenShift Service Mesh 3 by using the following NetworkPolicy example configuration:

   Sample policy

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: istio-istiod-v3
     namespace: istio-system
   spec:
     ingress:
       - {}
     podSelector:
       matchLabels:
         app: istiod
         istio.io/rev: istio-tenant-a 

   1

   
     policyTypes:
       - Ingress

   1

   Must match your current active revision name.

Procedure

1. Create your Istio resource.

   Example Istio resource

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: istio-tenant-a
   spec:
     namespace: istio-system-tenant-a 

   1

   
     version: v1.24.3
     values:
       meshConfig:
         discoverySelectors: 

   2

   
           - matchLabels:
               tenant: tenant-a
         extensionProviders:  

   3

   
           - name: prometheus
             prometheus: {}
           - name: otel
             opentelemetry:
               port: 4317
               service: otel-collector.opentelemetrycollector-3.svc.cluster.local

   1

   The spec.namespace field in your Istio resource must be the same namespace as your ServiceMeshControlPlane resource. If you set the spec.namespace field in your Istio resource to a different namespace than your ServiceMeshControlPlane resource, the migration does not complete successfully.

   2

   By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting discoverySelectors fields. In this example, the label tenant-a is used, but you can use any label or combination of labels.

   3

   Optional: If you are migrating metrics and tracing, update the extensionProviders fields according to your tracing and metrics configurations.

2. Add your tenant label to each one of your dataplane namespaces by running the following command for each dataplane namespace:

   $ oc label ns bookinfo tenant=tenant-a

   Note

   With OpenShift Service Mesh 2.6, namespaces were enrolled into the mesh by adding them to the ServiceMeshMemberRoll resource. In OpenShift Service Mesh 3, you must label each one of your dataplane namespaces to match your discoverySelectors fields.

Procedure

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

   $ oc get istios istio-tenant-a

   Example output

   NAME             REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
   istio-tenant-a   1           1       0        istio-tenant-a    Healthy   v1.24.3   30s

   Note

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

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

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

   $ oc label ns bookinfo istio.io/rev=istio-tenant-a maistra.io/ignore-namespace="true" --overwrite=true

   This adds the following labels to the namespace:

   1. The istio.io/rev: istio-tenant-a label: Ensures that any new pods that get created in that namespace connect to the OpenShift Service Mesh 3.0 proxy.

   2. The maistra.io/ignore-namespace: "true" label: Disables sidecar injection for OpenShift Service Mesh 2.6 proxies in the namespace so 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 will refuse 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 will connect to the OpenShift Service Mesh 3.0 proxy. Workloads can still communicate with each other regardless of which controlplane 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:

      Example command for bookinfo application

      $ oc rollout restart deployments -n bookinfo

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

      Example command with bookinfo application

      $ 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. Check that your workload is connected to the new control plane.

   1. Fetch the list of proxies that are still connected to the OpenShift Service Mesh 2.6 control plane with the istioctl tool by running the following command:

      $ istioctl ps --istioNamespace istio-system-tenant-a --revision basic

      In this example, basic is the name of your ServiceMeshControlPlane:

      Example output

         NAME                                              CLUSTER        CDS        LDS        EDS        RDS          ECDS         ISTIOD                            VERSION
         details-v1-7b49464bc-zr7nr.bookinfo               Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
         ratings-v1-d6f449f59-9rds2.bookinfo               Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
         reviews-v1-686cd989df-9x59z.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
         reviews-v2-785b8b48fc-l7xkj.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
         reviews-v3-67889ffd49-7bhxn.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8

   2. View the list proxies that have been migrated to the new OpenShift Service Mesh 3.0 control plane by running the following command:

      $ istioctl ps --istioNamespace istio-system-tenant-a --revision istio-tenant-a

      Example output

      NAME                                         CLUSTER        CDS        LDS        EDS        RDS        ECDS     ISTIOD                      VERSION
      productpage-v1-7745c5cc94-wpvth.bookinfo     Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED              istiod-5bbf98dccf-n8566     1.24.3

2. Verify your application is still working correctly. For the bookinfo application, run the following command:

   $ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage

Procedure

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

   Example ServiceMeshControlPlane cert-manager configuration

   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,istio-tenant-a}" 

   1

   1

   The app.istio.revisions field needs to 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. Create your Istio resource.

   Example Istio resource with cert-manager

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: istio-tenant-a
   spec:
     namespace: istio-system-tenant-a 

   1

   
     version: v1.24.3
     values:
       meshConfig:
         discoverySelectors: 

   2

   
           - matchLabels:
               tenant: tenant-a
         extensionProviders:  

   3

   
           - name: prometheus
             prometheus: {}
           - name: otel
             opentelemetry:
              port: 4317
              service: otel-collector.opentelemetrycollector-3.svc.cluster.local
       global:
         caAddress: cert-manager-istio-csr.istio-system.svc:443
       pilot:
         env:
           ENABLE_CA_SERVER: "false"

   1

   The spec.namespace field in your Istio resource must be the same namespace as your ServiceMeshControlPlane resource. If you set the spec.namespace field in your Istio resource to a different namespace than your ServiceMeshControlPlane resource, the migration will not work properly.

   2

   By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting discoverySelectors fields. In this example, the label tenant-a is used, but you can use any label or combination of labels.

   3

   Optional: If you are migrating metrics and tracing, update the extensionProviders fields according to your tracing and metrics configurations.

4. Add your tenant label to each one of your dataplane namespaces by running the following command for each dataplane namespace:

   $ oc label ns bookinfo tenant=tenant-a

   Note

   With OpenShift Service Mesh 2.6, namespaces were enrolled into the mesh by adding them to the ServiceMeshMemberRoll resource. In OpenShift Service Mesh 3, you must label each one of your dataplane namespaces to match your discoverySelectors fields.

Procedure

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

   $ oc get istios istio-tenant-a

   Example output

   NAME             REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
   istio-tenant-a   1           1       0        istio-tenant-a    Healthy   v1.24.3   30s

   Note

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

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

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

   $ oc label ns bookinfo istio.io/rev=istio-tenant-a maistra.io/ignore-namespace="true" --overwrite=true

   This adds the following labels to the namespace:

   1. The istio.io/rev: istio-tenant-a label: Ensures that any new pods that get created in that namespace connect to the OpenShift Service Mesh 3.0 proxy.

   2. The maistra.io/ignore-namespace: "true" label: Disables sidecar injection for OpenShift Service Mesh 2.6 proxies in the namespace so 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 will refuse 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 controlplane 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:

      Example command for bookinfo application

      $ oc rollout restart deployments -n bookinfo

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

      Example command with bookinfo application

      $ 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. Check that your workload is connected to the new control plane.

   1. Fetch the list of proxies that are still connected to the OpenShift Service Mesh 2.6 control plane with the istioctl tool by running the following command:

      $ istioctl ps --istioNamespace istio-system-tenant-a --revision basic

      In this example, basic is the name of your ServiceMeshControlPlane:

      Example output

         NAME                                              CLUSTER        CDS        LDS        EDS        RDS          ECDS         ISTIOD                            VERSION
         details-v1-7b49464bc-zr7nr.bookinfo               Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
         ratings-v1-d6f449f59-9rds2.bookinfo               Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
         reviews-v1-686cd989df-9x59z.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
         reviews-v2-785b8b48fc-l7xkj.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
         reviews-v3-67889ffd49-7bhxn.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8

   2. View the list proxies that have been migrated to the new OpenShift Service Mesh 3.0 control plane by running the following command:

      $ istioctl ps --istioNamespace istio-system-tenant-a --revision istio-tenant-a

      Example output

      NAME                                         CLUSTER        CDS        LDS        EDS        RDS        ECDS     ISTIOD                      VERSION
      productpage-v1-7745c5cc94-wpvth.bookinfo     Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED              istiod-5bbf98dccf-n8566     1.24.3

2. Verify your application is still working correctly. For the bookinfo application, run the following command:

   $ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage

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.

   Example Istio resource

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: ossm-3 

   1

   
   spec:
     updateStrategy:
       type: RevisionBased
     namespace: istio-system 

   2

   
     version: v1.26.8
     values:  

   3

   
       meshConfig:
         extensionProviders:
           - name: prometheus
             prometheus: {}
           - name: otel
             opentelemetry:
               port: 4317
               service: otel-collector.opentelemetrycollector-3.svc.cluster.local

   1

   The name, updateStrategy and version fields specify how the IstioRevision resource name is created. For more information, see "Identifying the revision name".

   2

   The 3.0 and 2.6 control planes must run in the same namespace.

   3

   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

Procedure

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

   Example ServiceMeshControlPlane cert-manager configuration

   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}" 

   1

   1

   The app.istio.revisions 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.

   Example Istio resource

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: ossm-3 

   1

   
   spec:
     updateStrategy:
       type: RevisionBased
     namespace: istio-system 

   2

   
     version: v1.26.8
     values:  

   3

   
       meshConfig:
         extensionProviders:
           - name: prometheus
             prometheus: {}
           - name: otel
             opentelemetry:
               port: 4317
               service: otel-collector.opentelemetrycollector-3.svc.cluster.local

   1

   The name, updateStrategy and version fields specify how the IstioRevision resource name is created. For more information, see "Identifying the revision name".

   2

   The 3.0 and 2.6 control planes must run in the same namespace.

   3

   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

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.

   Example Istio resource

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: ossm-3 

   1

   
   spec:
     updateStrategy:
       type: RevisionBased
     namespace: istio-system 

   2

   
     version: v1.24.3
     values:
       meshConfig:
         extensionProviders: 

   3

   
           - name: prometheus
             prometheus: {}
           - name: otel
             opentelemetry:
               port: 4317
               service: otel-collector.opentelemetrycollector-3.svc.cluster.local

   1

   The name, updateStrategy and version fields specify how the IstioRevision resource name is created. For more information, see "Identifying the revision name".

   2

   The 3.0 and 2.6 control planes must run in the same namespace.

   3

   Optional: 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 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

Procedure

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

   Example ServiceMeshControlPlane cert-manager configuration

   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}" 

   1

   1

   The app.istio.revisions 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.

   Example Istio resource

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: ossm-3 

   1

   
   spec:
     updateStrategy:
       type: RevisionBased
     namespace: istio-system 

   2

   
     version: v1.24.3
     values:
       meshConfig:
         extensionProviders: 

   3

   
           - name: prometheus
             prometheus: {}
           - name: otel
             opentelemetry:
               port: 4317
               service: otel-collector.opentelemetrycollector-3.svc.cluster.local

   1

   The name, updateStrategy and version fields specify how the IstioRevision resource name is created. For more information, see "Identifying the revision name".

   2

   The 3.0 and 2.6 control planes must run in the same namespace.

   3

   Optional: 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 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

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.

   Example Istio resource

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: default 

   1

   
   spec:
     updateStrategy:
       type: InPlace
     namespace: istio-system 

   2

   
     version: v1.24.3
     values:
       meshConfig:
         extensionProviders: 

   3

   
           - name: prometheus
             prometheus: {}
           - name: otel
             opentelemetry:
               port: 4317
               service: otel-collector.opentelemetrycollector-3.svc.cluster.local

   1

   The name, updateStrategy and version fields specify how the IstioRevision resource name is created. For more information, see "Identifying the revision name."

   2

   The 3.0 and 2.6 control planes must run in the same namespace.

   3

   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

Procedure

1. Run the following command to label the gateway namespace to ensure that gateway injection is enabled from the new mesh and add the maistra.io/ignore-namespace: "true" label:

   $ oc label namespace <gateway_namespace> istio.io/rev=<istio_revision_name> maistra.io/ignore-namespace="true"

   1. Remove the istio-injection=enabled label, if needed.

2. Deploy a canary gateway by using the following example:

   Example YAML for canary gateway

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: istio-ingressgateway-canary
     namespace: istio-ingress 

   1

   
   spec:
      selector:
        matchLabels:
          istio: ingressgateway 

   2

   
      template:
        metadata:
          annotations:
            inject.istio.io/templates: gateway
          labels:
            istio: ingressgateway
            istio.io/rev: canary 

   3

   
        spec:
          containers:
          - name: istio-proxy
            image: auto

   1

   Your Deployment resource must be in in the same namespace as your existing gateway.

   2

   Your spec.selector.matchlabels.istio parameter must match your existing gateway service selector.

   3

   Set your OpenShift Service Mesh 3.0 control plane revision as the value of the istio.io/rev label.

3. Ensure that the new gateway deployment is running with the new revision and is handling requests:

   1. Check that pods are running and in the Ready status.

   2. Check that the gateway is running the new revision by running the following command:

      $ istioctl ps -n istio-ingress

   3. Test a sample route through the gateway.

4. Gradually shift traffic between deployments:

   1. Increase replicas for new gateway by running the following command:

      $ oc scale -n istio-ingress deployment/<new_gateway_deployment> --replicas <new_number_of_replicas>

   2. Decrease replicas for old gateway by running the following command:

      $ oc scale -n istio-ingress deployment/<old_gateway_deployment> --replicas <new_number_of_replicas>

   3. Repeat this process, incrementally adjusting replica counts until the new gateway handles all traffic to the gateway Service.

Procedure

1. Run the following command to label the gateway namespace to ensure that gateway injection is enabled from the new mesh and add the maistra.io/ignore-namespace: "true" label:

   $ oc label namespace <gateway_namespace> istio.io/rev=<istio_revision_name> maistra.io/ignore-namespace="true"

   1. Remove the istio-injection=enabled label, if needed.

2. Restart the gateway deployment by running the following command:

   $ oc -n ${app_namespace} rollout restart deployment ${gateway_name}

Verification

1. Check that the gateway is running the new revision by running the following command:

   $ istioctl ps -n istio-ingress

2. Test application-specific routes.

Procedure

1. Recreate necessary network policies in the new OpenShift Service Mesh 3 control plane namespace.
2. Recreate network policies for each namespace that was part of the OpenShift Service Mesh 2 mesh.

3. Update labels.

   1. Update corresponding network policy selectors to match the new labels.

      Note

      Use a label scoped specifically to your mesh that you can reuse for discovery selectors.

Procedure

1. Verify that your new injection label is present in all workload namespaces.

2. Update the app.controller.configmapNamespaceSelector field 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.controller.configmapNamespaceSelector=tenant=tenant-a"

Procedure

1. Find all Service Mesh 2.6 resources by running the following command:

   $ oc get smcp,smm,smmr -A

2. Remove all ServiceMeshControlPlane resources by running the following command:

   $ oc delete smcp --all -A

3. Remove all ServiceMeshMemberRoll resources by running the following command:

   $ oc delete smmr --all -A

4. Remove all ServiceMeshMember resources by running the following command:

   $ oc delete smm --all -A

5. Verify that all resources were removed by running the following command:

   $ oc get smcp,smm,smmr -A

   Example output

   No resources found

Procedure

1. Check that there are no Red Hat OpenShift Service Mesh 2.6 resources left by running the following command:

   $ oc get smcp,smm,smmr -A

   Example output

   No resources found

2. Remove the Operator by running the following commands:

   1. Find the Operator subscription:

      csv=$(oc get subscription servicemeshoperator -n openshift-operators -o yaml | grep currentCSV | cut -f 2 -d ':')

   2. Delete the subscription:

      $ oc delete subscription servicemeshoperator -n openshift-operators

   3. Delete the clusterserviceversion CSV:

      $ oc delete clusterserviceversion $csv -n openshift-operators

3. Remove maistra CRDs by running the following command:

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

Procedure

1. Verify that all OpenShift Service Mesh 2.6 resources have been removed by running the following command:

   $ oc get smcp,smm,smmr -A

   Example output

   No resources found

2. Find namespaces with the maistra.io/ignore-namespace="true" label by running the following command:

   $ oc get namespace -l maistra.io/ignore-namespace="true"

   Example output

   NAME       STATUS   AGE
   bookinfo   Active   127m

3. Remove the label by running the following command:

   $ oc label namespace bookinfo maistra.io/ignore-namespace-

   Example output

   namespace/bookinfo unlabeled