openshift · skopacz1 · Dec 4, 2024 · Nov 8, 2024
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -6,6 +6,13 @@ Topics:
 - Name: Service Mesh 3.x release notes
   File: ossm-release-notes-assembly
 ---
+Name: Migrating from OpenShift Service Mesh 2.6
+Dir: migrating
+Distros: openshift-service-mesh
+Topics:
+- Name: Important information to know before migrating
+  File: ossm-migrating-read-me-assembly
+---
 Name: About
 Dir: about
 Distros: openshift-service-mesh

diff --git a/migrating/_attributes b/migrating/_attributes
@@ -0,0 +1 @@
+../_attributes
diff --git a/migrating/docinfo.xml b/migrating/docinfo.xml
@@ -0,0 +1,12 @@
+<title>Migrating</title>
+<productname>{product-title}</productname>
+<productnumber>{product-version}</productnumber>
+<subtitle>Migrating from OpenShift Service Mesh 2.6 to 3</subtitle>
+<abstract>
+    <para>This document provides important information on difference between {product-title} 2.6 and {product-title} 3, including a new operator, new resources, and changes to integrations like OpenShift Observability and Kiali. It also provides information on migrating from OpenShift Serivce Mesh 2.6 to OpenShift Service Mesh 3.
+    </para>
+</abstract>
+<authorgroup>
+    <orgname>Red Hat OpenShift Documentation Team</orgname>
+</authorgroup>
+<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/migrating/images b/migrating/images
@@ -0,0 +1 @@
+../images
diff --git a/migrating/modules b/migrating/modules
@@ -0,0 +1 @@
+../modules
diff --git a/migrating/ossm-migrating-read-me-assembly.adoc b/migrating/ossm-migrating-read-me-assembly.adoc
@@ -0,0 +1,96 @@
+:_mod-docs-content-type: ASSEMBLY
+[id=ossm-migrating-read-me-assembly]
+= Important information to know if you are migrating from OpenShift Service Mesh 2.6
+include::_attributes/common-attributes.adoc[]
+:context: ossm-migrating-read-me-assembly
+
+toc::[]
+
+If you are moving from {SMProductName} 2.6 to {SMProductName} 3, read the content in this section first as it contains important information and explanations on the differences between the versions. These differences have a direct impact on your installation and configuration of {SMProduct} 3.
+
+include::modules/ossm-migrating-2-and-3-differences.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-new-operator.adoc[leveloffset=+1]
+
+.Next steps
+You can install the {SMProduct} 3 Operator, or you can run {SMProduct} 2.6 and {SMProduct} 3 in the same cluster using either the multi-tenant deployment model, or the cluster-wide model.
+
+* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-installing-operator_ossm-about-deployment-and-update-strategies[Installing the Service Mesh Operator]
+* xref:../install/ossm-running-v2-same-cluster-as-v3-assembly.adoc#ossm-running-v2-v3-multitenant-deployment-model_ossm-running-v2-same-cluster-as-v3-assembly[Running OpenShift Service Mesh 2.6 and OpenShift Service Mesh 3 using multi-tenant model]
+* xref:../install/ossm-running-v2-same-cluster-as-v3-assembly.adoc#ossm-running-v2-v3-cluster-wide-deployment-model_ossm-running-v2-same-cluster-as-v3-assembly[Running OpenShift Service Mesh 2.6 and OpenShift Service Mesh 3 using cluster-wide deployment model]
+
+include::modules/ossm-migrating-read-me-new-resources.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-observability-integrations.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc[leveloffset=+1]
+
+.Next steps
+* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-about-discoveryselectors_ossm-scoping-service-mesh-with-discoveryselectors[Scoping Service Mesh with discoverySelectors]
+
+include::modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-independently-managed-gateways.adoc[leveloffset=+1]
+
+.Next steps
+If you are using {SMProduct} 2.6, and have not migrated from `ServiceMeshControlPlane` defined gateways to gateway injection, then you must follow the {SMProduct} 2.x gateway migration procedure before you can move to {SMProduct} 3.
+
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-about-gateway-migration_gateway-migration[Gateway migration]
+
+include::modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-introducing-canary-updates.adoc[leveloffset=+1]
+
+.Next steps
+You can set `updateStrategy` to `RevisionBased` to use canary updates.
+
+* xref:../update/ossm-updating-openshift-service-mesh.adoc#about-revisionbased-strategy_ossm-performing-inplace-update[About RevisionBased strategy]
+
+Be aware that setting the `updateStrategy` to `RevisionBased` also has implications for some integrations with {SMProduct}, such as the cert-manager tool integration.
+
+* xref:../install/ossm-cert-manager-assembly.adoc#updating-istio-csr-revision-based-only_ossm-cert-manager-assembly[Updating istio-csr agents with revision-based update strategies]
+
+include::modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-support-for-istioctl.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc[leveloffset=+1]
+include::modules/ossm-migrating-read-me-tls-configuration-change.adoc[leveloffset=+1]
+
+//comments will be removed for OSSM 3.0 GA. For future reference only as Gwynne will likely be living in this file for Q1 2025.
+//Migrating dir will be similar to Observability dir structure. Something like:
+//Dir: migrating
+//Distros: openshift-service-mesh
+//Topics:
+//-Name: Migration Guides
+// File: ossm-file-name
+//- Name: Migrating Metrics
+//  Dir: mig dir name1
+//  Topics:
+//  - Name: Migrating metrics guide
+//    File: ossm-file-name2
+//- Name: Migratiing Traces
+//  Dir: mig dir name2
+// Topics:
+// - Name: Migrating traces
+//    File: ossm-file-name3
+//- Name: Migrating from Kiali to Kiali 2
+//  Dir: kiali
+//  Topics:
+//  - Name: Something about Kiali
+//    File: ossm-file-name4
+//Will be dependent on both the number of and type of migrations that need to take place to move from 2.6 to 3.
+//migrating-read-me is the only content we have as of 11/19/2024.
+//Possible file names will change once doc work can start on migration guides. As of 11/19/2024 it is unclear what migration guides will need to be created as engineering work is incomplete, and it is unknown how migration will happen. Will the operator have to go first? Do the integrations have to go in a particular order? Will there be differences if customers choose RevisionBased instead of the default InPlace update strategy? There are more questions than answers, so setting it up as best I can with the knowledge I have at this time.
+//Possible each module will have Next Steps that will link out to respective migration guide.
+
+[role="_additional-resources"]
+[id="addition-resource_{context}"]
+== Additional Resources
+
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/#Observability[Red Hat OpenShift Observability]
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/logging/index[Logging]
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/monitoring/index[User workload monitoring]
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/distributed_tracing/index[{DTProductName}]
+* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/[Labels and Selectors] (Kubernetes documentation)
+* link:https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/[Istio Workload Minimum TLS Version Configuration] (Istio documentation)
+* link:https://istio.io/latest/docs/reference/config/security/authorization-policy/[Authorization Policies] (Istio documentation)
+
+//influx. Will be part of larger content strategy/IA effort to bridge 2.x users on their way to moving to 3.x
+//Start of an overall Migrating section.
+//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc.
+//Migration likely to resemble https://docs.openshift.com/container-platform/4.17/migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.html#about-migrating-from-3-to-4 when done for OSSM 3.0 GA.
diff --git a/migrating/snippets b/migrating/snippets
@@ -0,0 +1 @@
+../snippets
diff --git a/modules/ossm-migrating-2-and-3-differences.adoc b/modules/ossm-migrating-2-and-3-differences.adoc
@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc
+
+//Start of an overall Migrating section.
+//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc.
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-2-and-3-differences_{context}"]
+= Differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3
+
+If you are a current {SMProductName} user, there are a number of important differences you need to understand between {SMProduct} 2 and {SMProduct} 3 before you migrate, including the following:
+
+* A new Operator
+* Integrations like Observability and Kiali are installed separately
+* New resources: `Istio` and `IstioCNI`
+* Scoping of a mesh with `discoverySelectors` and labels
+* New considerations for sidecar injection
+* Support for multiple control planes
+* Independently managed gateways
+* Explicit Istio OpenShift route creation
+* Canary upgrades
+* Support for Istio multi-cluster topologies
+* Support for Istioctl
+* Change to Kubernetes network policy management
+* Transport layer security (TLS) configuration change
+
+You must be using {SMProduct} 2.6 to migrate to {SMProduct} 3.
diff --git a/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc b/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc
@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc
+
+//Start of an overall Migrating section.
+//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc.
+
+:_mod-docs-content-type: CONCEPT
+[id="explicitly-create-openshift-routes_{context}"]
+= Explicitly create OpenShift Routes
+//In the ocp-docs repo, there is no attribute for OpenShift Container Platform Ingress Operator so followed https://docs.openshift.com/container-platform/4.17/networking/ingress-operator.html
+An OpenShift `Route` resource allows an application to be exposed with a public URL using {ocp-product-title} Ingress Operator for managing HAProxy based Ingress controllers.
+
+{SMProductName} 2 used Istio OpenShift Routing (IOR) that automatically created and managed OpenShift routes for Istio gateways. While this was convenient, as the Operator managed these routes for you, it also caused confusion around ownership as many `Route` resources are managed by administrators. Istio OpenShift Routing also lacked the ability to configure an independent `Route` resource, created unnecessary routes, and exhibited unpredictable behavior during updates.
+
+Thus, in {SMProduct} 3, when a `Route` is desired to expose an Istio gateway, you must create and manage it manually. You can also expose an Istio gateway through a Kubernetes service of type `LoadBalancer` if a route is not desired.
diff --git a/modules/ossm-migrating-read-me-independently-managed-gateways.adoc b/modules/ossm-migrating-read-me-independently-managed-gateways.adoc
@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc
+
+//Start of an overall Migrating section.
+//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc.
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-migrating-read-me-independently-managed-istio-gateways_{context}"]
+= Independently managed Istio gateways
+
+In Istio, gateways are used to manage traffic entering (ingress) and exiting (egress) the mesh. {SMProductName} 2 deployed and managed an ingress gateway and an egress gateway with the Service Mesh control plane. Both an ingress gateway and an egress gateway were configured using the `ServiceMeshControlPlane` resource.
+
+The {SMProduct} 3 Operator does not create or manage gateways.
+
+Instead, gateways in {SMProduct} 3 are created and managed independent of the Operator and control plane using gateway injection or the Kubernetes Gateway API. This provides greater flexibility and ensures that gateways can be fully customized and managed as part of a Red Hat OpenShift GitOps pipeline. This allows the gateways to be deployed and managed alongside their applications with the same lifecycle.
+
+//Note to add GitOps attributes to common-attributes file. Adding attributes is being handled by a different Jira issue, and is outside the scope of this PR.
+
+This change was made for two reasons:
+
+* To start with a gateway configuration that can expand over time to meet the more robust needs of a production environment.
+* Gateways are better managed together with their corresponding workloads.
+
+Gateways may continue to be deployed onto nodes or namespaces independent of applications. For example, a centralized gateway node. Istio gateways also remain eligible to be deployed on {ocp-product-title} infrastructure nodes.
+
+//Note to check if OpenShift Container Platform Infrastructure Nodes (or maybe OpenShift Infrastructure Nodes) has an attribute, and if it does, add it to service-mesh-docs-main _attributes file, which is being handled by a separate Jira and running spreadsheet.
diff --git a/modules/ossm-migrating-read-me-introducing-canary-updates.adoc b/modules/ossm-migrating-read-me-introducing-canary-updates.adoc
@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc
+
+//Start of an overall Migrating section.
+//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc.
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-migrating-read-me-introducing-canary-updatess_{context}"]
+= Introducing canary updates
+
+{SMProductName} 2 supported only in-place style updates, which created risk for large meshes where, after the control plane was updated, all workloads must update to the new control plane version without a simple way to roll back if something goes wrong.
+
+{SMProduct} 3 retains support for simple in-place style updates, and adds support for canary-style updatess of the Istio control plane using Istio's revision feature.
+
+The `Istio` resource manages Istio revision labels using the `IstioRevision` resource. When the `Istio` resource's `updateStrategy` type is set to `RevisionBased`, it creates Istio revision labels using the `Istio` resource's name combined with the Istio version, for example `mymesh-v1-21-2`.
+
+During an updates, a new `IstioRevision` deploys the new Istio control plane with an updated revision label, for example `mymesh-v1-22-0`. Workloads can then be migrated between control planes using the revision label on namespaces or workloads, for example `istio.io/rev=mymesh-v1-22-0`.
+
+Setting your `updateStrategy` to `RevisionBased` also has implications for integrations, such as the cert-manager tool, and gateways.
diff --git a/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc b/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc
@@ -0,0 +1,17 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc
+
+//Start of an overall Migrating section.
+//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc.
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-migrating-read-me-kubernetes-network-policy-management_{context}"]
+= Kubernetes network policy management
+
+By default, {SMProductName} 2 created Kubernetes `NetworkPolicy` resources with the following behavior:
+
+* Ensured network applications and the control plane could communicate with each other.
+* Restricted ingress for mesh applications to only member projects.
+
+{SMProduct} 3 does not create these policies. Instead, you must configure the level of isolation required for your environment. Istio provides fine grained access control of service mesh workloads through Authorization Policies. For more information, see "Authorization Policies".