Create ossm-migrating-from-2-to-3-assembly file that will sit in /migrating and act as the hub/starting point that explains the migration guides, expectations, and how to use them.
 
:_mod-docs-content-type: ASSEMBLY
[id=ossm-migrating-from-2-to-3-assembly]
= Migrating from OpenShift Service Mesh 2.6.z to 3.0
include::_attributes/common-attributes.adoc[]
:context: ossm-migrating-from-2-to-3-assembly

toc::[]

The informational content and step-by-step guides contained within this migration section applies only if:

• You are an existing {SMProductName} user running {SMProduct} {SMv2Version}
• You want to move to {SMProduct} 3.0
  If you are an existing user but you are not running {SMProduct} {SMv2Version} version, you must update before you can continue. Here's how: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-versioning_ossm-upgrade[Upgrading Service Mesh].

[NOTE]
====
From time to time, you may need to reference, or will be directed, to {SMProduct} 2.x content. All {SMProduct} 2.x content is available here: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x[OpenShift Service Mesh 2.x].
====

//02/04/2024: Per Service Mesh Program Call, there will be a 2.6.6 release with 3.0, so users will need to upgrade to 2.6.6. UPDATE THE VARIABLE IN COMMON_ATTRIBUTES ACCORDINGLY
//it looks like the latest z-stream will be 2.6.5, set to release on Feb 5, 2025. Unless there is a z-stream in Feb, 2.6.5 is likely the version to be listed for 2.6.z.

== Recommendations

Given the nature of migrating to a brand new operator, the following are recommendations to keep the risk of misconfigurations or possible conflicts to minimum:

• Do not upgrade OpenShift Service Mesh 2 operator or control planes in the middle of the migration

• After the OpenShift Service Mesh 3 operator is installed and migration of data plane is in progress, it's not recommended to upgrade OpenShift Service Mesh 2 operator or control planes. This can be achieved by switching from Automatic Operator Update approval to Manual.

• Keep the amount of the service mesh configuration changes to minimum during the migration

• It's not recommended to change Istio resources for traffic management or security or add new workloads or gateways to the service mesh in the middle of the migration.

[NOTE]
====
If it's necessary to add a new workload namespace during the migration, it should be managed by The {SMProduct} 3.0 control plane and it MUST be labeled with `maistra.io/ignore-namespace: "true"` to avoid conflicts between 3.0 and and {SMProduct} 2 `ServiceMeshControlPlane`.
====

• Finish the migration without unnecessary delays

Once the migration is started, it should be completed as quickly as possible without unnecessary delays.

== How to use the migration guides

The migration guides are designed to help you move from {SMProduct} {SMv2Version} to {SMProduct} 3.0, based on your deployment model:

• Mulitenant
• Mulitenant with cert-manager
• Cluster-wide
• Cluster-wide with cert-manager

You can also migrate the following <insert appropriate word/term here>:

• {KialiProduct}
• Gateways using gateway injection

=== Premigration steps

Before you begin, do the following:

• Read "Important information to know before you migrate" as it contains information, and provides context, on the differences between {smproduct} 2.x and {smproduct} 3.x. These differences have a direct impact on your installation and configuration of {SMProduct} 3. <insert exref here>
• Review and complete the "Premigration checklists" <insert exref here>
• If you use {kialiproduct}, read "<insert actual name>" as it contains changes between Kiali v1 and Kiali v2. <insert exref here>

The last step of "Premigration Checklist" is to run a script to verify your deployment is ready to migrate. From there, you can either go to the specific instructions for your deployment model, or check if you are using cert-manager and then follow the cert-manager instructions for your deployment model.

== After you have completed your migration

After you have completed your migration, you can add new workloads, recreate network policies, and take advantage of all that {SMProduct} 3.x has to offer.

//may somehow need to link to both of those, perhaps in a "Next steps" instead of a bulleted list. This assembly may need to be the first thing users see when they go to Service Mesh 3.0 > Migration Guides