Merge pull request #40317 from JStickler/OSSMDOC-437

OSSMDOC-437: Upgrade revisions and maistra.io label warning.

Author: JStickler

_topic_maps/_topic_map.yml

@@ -2756,9 +2756,7 @@ Topics:
     File: ossm-create-mesh
   - Name: Enabling sidecar injection
     File: prepare-to-deploy-applications-ossm
-  - Name: Upgrading from 2.0 to 2.1
-    File: upgrading-ossm-to-2-1
-  - Name: Upgrading from 1.1 to 2.0
+  - Name: Upgrading Service Mesh
     File: upgrading-ossm
   - Name: Managing users and profiles
     File: ossm-profiles-users

modules/ossm-migrating-to-20.adoc

@@ -4,11 +4,13 @@
 // * service_mesh/v2x/ossm-troubleshooting.adoc
 
 [id="ossm-versions_{context}"]
-= Understanding Service Mesh versioning
+= Understanding Service Mesh versions
 
-The {ProductName} 2.0 Operator supports both v1 and v2 service meshes.
+In order to understand what version of {ProductName} you have deployed on your system, you need to understand how each of the component versions is managed.
 
-* *Operator* version - The current Operator version is {ProductVersion}. This version number only indicates the version of the currently installed Operator. This version number is controlled by the intersection of the *Update Channel* and *Approval Strategy* specified in your Operator subscription. The version of the Operator does not determine which version of the `ServiceMeshControlPlane` resource is deployed. Upgrading to the latest Operator does *not* automatically upgrade your service mesh control plane to the latest version.
+The {ProductName} 2.x Operator supports both v1x and v2x service meshes.
+
+* *Operator* version - The current Operator version is {ProductVersion}. This version number only indicates the version of the currently installed Operator. This version number is controlled by the intersection of the *Update Channel* and *Approval Strategy* specified in your Operator subscription. The version of the Operator does not determine which version of the `ServiceMeshControlPlane` resource is deployed.
 +
 [IMPORTANT]
 ====
@@ -21,6 +23,6 @@ Upgrading to the latest Operator version does not automatically upgrade your con
 
 ** To configure in the YAML View, set the value for `spec.version` in the YAML file.
 
-* *Control Plane* version - The version parameter specified within the SMCP resource file as `spec.version`. Supported versions are v1.1 and v2.0.
+* *Control Plane* version - The version parameter specified within the SMCP resource file as `spec.version`. Supported versions are v1.1, v2.0, and v2.1.
 
-The Operator Lifecycle Manager (OLM) does not manage upgrades from v1 to v2, so the version number for your Operator and `ServiceMeshControlPlane` (SMCP) may not match, unless you have manually upgraded your SMCP.
+Operator Lifecycle Manager (OLM) does not manage control plane upgrades, so the version number for your Operator and `ServiceMeshControlPlane` (SMCP) may not match, unless you have manually upgraded your SMCP.

modules/ossm-understanding-versions.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/upgrading-ossm.adoc
+
+[id="ossm-upgrade-considerations_{context}"]
+= Upgrade considerations
+
+The `maistra.io/` label or annotation should not be used on a user-created custom resource, because it indicates that the resource was generated by and should be managed by the {ProductName} Operator.
+
+[WARNING]
+====
+During the upgrade, the Operator makes changes, including deleting or replacing files, to resources that include the following labels or annotations that indicate that the resource is managed by the Operator.
+====
+
+Before upgrading check for user-created custom resources that include the following labels or annotations:
+
+* `maistra.io/` AND the `app.kubernetes.io/managed-by` label set to `maistra-istio-operator` ({ProductName})
+
+* `kiali.io/` (Kiali)
+
+* `jaegertracing.io/` ({JaegerName})
+
+* `logging.openshift.io/` (Red Hat Elasticsearch)
+
+Before upgrading, check your user-created custom resources for labels or annotations that indicate they are Operator managed. Remove the label or annotation from custom resources that you do not want to be managed by the Operator.
+
+When upgrading to version 2.0, the Operator only deletes resources with these labels in the same namespace as the SMCP.
+
+When upgrading to version 2.1, the Operator deletes resources with these labels in all namespaces.

modules/ossm-upgrade-considerations.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/upgrading-ossm.adoc
+
+[id="ossm-upgrading-operator_{context}"]
+= Upgrading the Operators
+
+[IMPORTANT]
+====
+The version of the Operator does _not_ determine the version of your service mesh. The current Operator supports both v1 and v2 service meshes.
+
+Updating the Operator does not affect the version of any component other than the Operator. Updating the Operators does _not_ update the `ServiceMeshControlPlane` version or deployments.
+====
+
+When you installed your Operators, you selected an *Update Channel* and an *Approval Strategy*. Those two settings determine when and how your Operators are updated.
+
+.Interaction of Update Channel and Approval Strategy
+[options="header"]
+[cols="a, a, a"]
+|====
+| |Versioned channel|"Stable" or "Preview" channel
+|*Automatic*
+|Automatically updates Operator for minor and patch releases for that version only. Will not automatically update to the next major version (that is, from version 2.0 to 3.0). Manual change to Operator subscription required to update to the next major version.
+|Automatically updates Operator for all major, minor, and patch releases.
+
+|*Manual*
+|Manual updates required for minor and patch releases for the specified version. Manual change to Operator subscription required to update to the next major version.
+|Manual updates required for all major, minor, and patch releases.
+|====

modules/ossm-upgrading-operator.adoc

@@ -1,9 +1,8 @@
-[id="upgrading-ossm-to-2-1"]
-= Upgrading Service Mesh from version 2.0 to version 2.1
-include::modules/ossm-document-attributes.adoc[]
-:context: upgrading-ossm-to-2-1
+// Module included in the following assemblies:
+// * service_mesh/v2x/upgrading-ossm.adoc
 
-toc::[]
+[id="ossm-upgrading-to-21_{context}"]
+= Upgrading {ProductName} from version 2.0 to version 2.1
 
 Upgrading from version 2.0 to 2.1 requires manual steps that migrate your workloads and application to a new instance of {ProductName} running the new version.