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

      Next steps for migrating with the cert-manager tool

      There are some configurations you must complete first before you can start migrating your deployments:

      • "Migrating a multitenant deployment with the cert-manager tool"
      • "Cluster-wide migration methods"

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:

   You can see the following example configuration for 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

   You can see the following example configuration for 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

   You can see the following example configuration for 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

   You can see the following example configuration for an 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

   You can see the following example configuration for 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

   You can see the following example configuration for an 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:

   You can see the following example configuration for 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:

   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

   Note

   You must match your current active revision name through the istio.io/rev label in your second Istiod network policy.

Procedure

1. Create your Istio resource.

   You can see the following example configuration for reference:

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: istio-tenant-a
   spec:
     namespace: istio-system-tenant-a
     version: v1.24.3
     values:
       meshConfig:
         discoverySelectors:
           - matchLabels:
               tenant: tenant-a
         extensionProviders:
           - name: prometheus
             prometheus: {}
           - name: otel
             opentelemetry:
               port: 4317
               service: otel-collector.opentelemetrycollector-3.svc.cluster.local

   • spec.namespace specifies the 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.
   • spec.values.meshConfig.discoverySelectors specifies the labels that the control plane uses to identify the namespaces it should manage. 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.
   • spec.values.meshConfig.extensionProviders specifies the metrics and tracing configurations for the control plane. 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:

      $ 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. 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 the following example, basic is the name of your ServiceMeshControlPlane:

         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:

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

   where:

   app.istio.revisions

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

   You can see the following example configuration for reference:

   apiVersion: sailoperator.io/v1
   kind: Istio
   metadata:
     name: istio-tenant-a
   spec:
     namespace: istio-system-tenant-a
     version: v1.24.3
     values:
       meshConfig:
         discoverySelectors:
           - matchLabels:
               tenant: tenant-a
         extensionProviders:
           - 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"

   • spec.namespace specifies the namespace for 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.
   • spec.values.meshConfig.discoverySelectors specifies the label selector for your Istio resource. 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.
   • spec.values.meshConfig.extensionProviders is an optional field. 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:

      $ 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. 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 the following example, basic is the name of your ServiceMeshControlPlane:

         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.

   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

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

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

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

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

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:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: istio-ingressgateway-canary
     namespace: istio-ingress
   spec:
      selector:
        matchLabels:
          istio: ingressgateway
      template:
        metadata:
          annotations:
            inject.istio.io/templates: gateway
          labels:
            istio: ingressgateway
            istio.io/rev: canary
        spec:
          containers:
          - name: istio-proxy
            image: auto

   • metadata.namespace specifies the namespace for your Deployment resource must be in the same namespace as your existing gateway.
   • spec.selector.matchLabels.istio specifies the label selector for your Deployment resource that must match your existing gateway service selector.
   • spec.template.metadata.labels.istio.io/rev sets 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. Re-create necessary network policies in the new OpenShift Service Mesh 3 control plane namespace.
2. Re-create 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:

   1. Find the Operator subscription by running the following command:

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

   2. Delete the subscription by running the following command:

      $ oc delete subscription servicemeshoperator -n openshift-operators

   3. Delete the clusterserviceversion CSV by running the following command:

      $ 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