OSSM-8958: Cluster-wide migration using istio injection label

migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc

@@ -17,6 +17,7 @@ include::modules/ossm-control-plane-configuration-migration-requirements.adoc[le
 
 include::modules/ossm-cluster-wide-migration-methods.adoc[leveloffset=+1]
 
+// The following tasks are for migration using the Istio revision label
 include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -33,3 +34,30 @@ include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespa
 You can proceed to complete the migration and remove {SMProduct} 2 resources.
 
 * xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration]
+
+// The following tasks are for migration using the Istio injection label
+include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name]
+
+include::modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc[leveloffset=+2]
+
+.Next steps
+
+If you are using gateways, you must migrate them before you complete the migration process.
+
+* xref:../../migrating/migrating-gateways/ossm-migrating-gateways-assembly.adoc[Migrating gateways from Service Mesh 2 to Service Mesh 3]
+
+If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and re-label namespaces.
+
+[IMPORTANT]
+====
+Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways.
+====
+
+// insert xref to "Creating the default revision tag and relabeling the namespaces" after PR OSSM-9000 is merged
+
+* Creating the default revision tag and relabeling the namespaces

modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc

@@ -0,0 +1,101 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label_{context}"]
+= Migrating a cluster-wide deployment by using the istio injection label
+
+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 {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping".
+
+.Prerequisites
+
+* You have deployed {ocp-product-title} 4.14 or later.
+* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role.
+* You have completed the premigration checklists.
+* You have the {SMProduct} {SMv2Version} Operator installed.
+* You have the {SMProduct} 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
+
+. Identify the namespaces that contain a 2.6 control plane by running the following command:
++
+[source,terminal]
+----
+$ oc get smcp -A
+----
++
+.Example output
+[source,terminal]
+----
+NAMESPACE      NAME                   READY   STATUS            PROFILES      VERSION   AGE
+istio-system   install-istio-system   6/6     ComponentsReady   ["default"]   2.6.6     115m
+----
+
+. 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
+[source,yaml,subs="attributes,verbatim"]
+----
+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 {SMProduct} 3.0 control plane from injecting proxies in the namespaces that have the `istio-injection=enabled` label applied and are still managed by {SMProduct} 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.
+====
+
+. Apply the YAML file by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f ossm-3.yaml
+----
+
+.Verification
+
+. Verify that the new `istiod` resource uses the existing root certificate by running the following command:
++
+[source,terminal]
+----
+$ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret'
+----
++
+.Example output
+[source,terminal]
+----
+2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret
+----

modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc

@@ -0,0 +1,113 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-migrating-workloads-using-the-istio-injection-label_{context}"]
+= Migrating workloads by using the istio injection label
+
+Now you can migrate your workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane.
+
+[NOTE]
+====
+You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways".
+====
+
+.Procedure
+
+. Find the current `IstioRevision` resource for your {SMProduct} 3.0 control plane by running the following command:
++
+[source,terminal]
+----
+$ oc get istios
+----
++
+.Example output
++
+[source,terminal]
+----
+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
+----
+
+. 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.
+====
+
+. Update the injection labels on the data plane namespace by running the following command:
++
+[source,terminal]
+----
+$ 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:
+
+.. 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. 
+
+.. 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 {SMProduct} 3.0 proxy.
+
+.. Adds the `maistra.io/ignore-namespace: "true"` label: This label disables sidecar injection for {SMProduct} 2.6 proxies in the namespace. With the label applied, {SMProduct} 2.6 stops injecting proxies in this namespace, and any new proxies are injected by {SMProduct} 3.0. Without this label, the {SMProduct} 2.6 injection webhook tries to inject the pod and the injected sidecar proxy refuses to start since it will has both the {SMProduct} 2.6 and the {SMProduct} 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 {SMProduct} 3.0 proxy. Workloads can still communicate with each other regardless of which control plane they are connected to.
+====
+
+. Restart the workloads by using one of the following options:
++
+.. To restart all the workloads at the same time so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command:
++
+.Example command for `bookinfo` application
+[source,terminal]
+----
+$ oc rollout restart deployments -n bookinfo
+----
+
+.. To restart each workload individually, run the following command for each workload:
++
+.Example command for `bookinfo` application
+[source,terminal]
+----
+$ oc rollout restart deployments productpage-v1 -n bookinfo
+----
+
+. Wait for the `productpage` application to restart by running the following command:
++
+[source,terminal]
+----
+$ oc rollout status deployment productpage-v1 -n bookinfo
+----
+
+.Verification
+
+. Verify that the the new control plane manages the expected workloads by running the following command:
++
+[source,terminal]
+----
+$ istioctl ps -n bookinfo
+----
++
+.Example output:
+[source,terminal]
+----
+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.
+
+. If the 2.6 installation contains 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.
+====