Upgrade from OpenShift Service Mesh 2.6 to 3.0 with Kiali

Red Hat OpenShift Service Mesh 3.0 is upon us and with it comes new ways to manage your mesh. Canary upgrades of your control plane are now possible with 3.0, and the migration process from OpenShift Service Mesh 2.6 to 3.0 utilizes a canary upgrade to minimize downtime while upgrading. 

In a canary upgrade, you have two separate instances of your control plane: the current version and the new version. Each instance of a control plane is called a revision. You use labels to control which control plane revision handles proxy injection for a namespace or workload. In order to upgrade from the current control plane revision to the new control plane revision, you update the revision label on your namespace then restart all your workloads in that namespace to re-inject sidecar proxies that communicate with the new control plane. Kiali's mesh page helps during this process.

The mesh page shows you all your control plane revisions and which namespaces (data plane) they manage. During your upgrade from OpenShift Service Mesh 2.6 to 3.0, the mesh page helps you visualize which namespaces are still on 2.6 and which namespaces have been upgraded to 3.0. In this article, we'll explore how you can use Kiali's mesh page to track namespaces during a migration. For a more in-depth migration guide, see the OpenShift Service Mesh migration documentation.

Setup

In this example, we have:

• An OpenShift Service Mesh 2.6 ServiceMeshControlPlane resource named basic in the istio-system namespace:

  apiVersion: maistra.io/v2
  kind: ServiceMeshControlPlane
  metadata:
    name: basic
    namespace: istio-system
  spec:                                                                                                                                                                                                                                                                                     
    addons:                                                                                                             
      kiali:                                                            
        enabled: false                                                  
      prometheus:                                                       
        enabled: false                                                  
    gateways:                                                           
      enabled: false                                                    
      openshiftRoute:                                                   
        enabled: false                                                  
    meshConfig:                                                         
      extensionProviders:                                               
      - name: prometheus                                                
        prometheus: {}                                                  
    mode: ClusterWide                                                                                                        
    security:                                                           
      manageNetworkPolicy: false                                                                                           
    tracing:                                                            
      type: None                                                        
    version: v2.6

• An OpenShift Service Mesh 3.0 Istio resource named ossm3 in the istio-system namespace:

  apiVersion: sailoperator.io/v1
  kind: Istio
  metadata:
    name: ossm3
  spec:
    namespace: istio-system
    updateStrategy:                                                     
      type: InPlace

• Kiali in the istio-system namespace configured with Prometheus. You can use any Prometheus, but in this demo we're using OpenShift User-Workload Monitoring:

  apiVersion: kiali.io/v1alpha1
  kind: Kiali
  metadata:
    name: kiali
    namespace: istio-system
  spec:
    external_services:
      grafana:
        enabled: false
      prometheus:
        auth:
          type: bearer
          use_kiali_token: true
        thanos_proxy:
          enabled: true
        url: https://thanos-querier.openshift-monitoring.svc.cluster.local:9091

• Five workload namespaces that are being managed by the 2.6 ServiceMeshControlPlane.
• Prometheus. 

Let’s open Kiali (Figure 1) and navigate to the mesh page to see how this looks.

You can see each control plane revision, istiod-ossm3 and istiod-basic, is shown along with the data plane and Prometheus. The istiod-basic revision, our ServiceMeshControlPlane, is managing all namespaces in our data plane. This is represented on the mesh page by the edge going from the istiod-basic control plane node to the data plane node.

Zooming in to the right, the side panel shows a summary of the different parts of your mesh, as depicted in Figure 2.

Clicking the data plane node will show you a summary of all namespaces managed by the associated control plane (Figure 3).

Migration

Now let's begin migrating our workloads from our OpenShift Service Mesh 2.6 control plane to our OpenShift Service Mesh 3.0 control plane. Our five workload namespaces are mercury, venus, earth, mars, and jupiter. We're going to update three labels on our namespaces, maistra.io/ignore-namespace: "true", istio-injection , and istio.io/rev: ossm3 labels. 

The first maistra.io/ignore-namespace label prevents our 2.6 control plane from attempting to inject a sidecar proxy into pods in that namespace. We only want our 3.0 control plane injecting sidecars into the namespace. The second label istio-injection can prevent proxy injection by our 3.0 control plane if it's present, so we will remove it here. The istio.io/rev label allows our 3.0 control plane to inject a proxy. We will update all labels at the same time.

Note that the exact labels you use will depend on what mode (MultiTenant versus ClusterWide) your ServiceMeshControlPlane uses, the upgrade strategy for your Istio, and which migration path you choose. Please see the 3.0 migration documentation for more details on which upgrade procedure to follow along with a more in-depth guide.

Migrating a namespace

We'll start by migrating our mercury namespace. First we will label the namespace:

kubectl label namespace mercury maistra.io/ignore-namespace="true" istio-injection- istio.io/rev=ossm3 --overwrite=true

Then we will restart the workloads inside that namespace:

kubectl rollout restart deployment -n mercury && kubectl rollout status deployment -n mercury

Looking back at the mesh page, we see there's now two data plane nodes, one for each control plane revision. There's also an edge from each revision to the data plane it manages. See Figure 4.

Clicking the istio-system namespace box will show a summary of the control planes in the side panel on the right.

If you select the data plane associated with (i.e., has an edge from) the istiod-ossm3 control plane, you'll see the mercury namespace in the summary panel since we have migrated that namespace, as shown in Figure 5.

Finish the migration

Once we repeat this process with our remaining workload namespaces, we can now see the 2.6 data plane node has disappeared and the 3.0 data plane node manages all five namespaces. This is shown in Figure 6.

Clean up

We have finished migrating all of our workloads to our OpenShift Service Mesh 3.0 control plane. We will now remove our OpenShift Service Mesh 2.6 control plane:

kubectl delete smcp basic -n istio-system

Looking back at the mesh page, we can see our 2.6 control plane revision has been removed as well (Figure 7).

Wrap up

Migrating your workloads from your OpenShift Service Mesh 2.6 control plane to your OpenShift Service Mesh 3.0 control plane is the same process as a canary upgrade. Kiali's mesh page helps you during canary upgrades by showing your control plane revisions and the namespaces they manage.

Keep learning about OpenShift Service Mesh, or visit our service mesh topic page for more information.