Merge pull request #48812 from JStickler/OSSMDOC-628

OSSMDOC-628: Update upgrade page and address common questions.

Author: JStickler

modules/ossm-understanding-versioning.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/upgrading-ossm.adoc
+
+[id="ossm-versioning_{context}"]
+= Understanding versioning
+
+Red Hat uses semantic versioning for product releases. Semantic Versioning is a 3-component number in the format of X.Y.Z, where:
+
+* X stands for a Major version. Major releases usually denote some sort of breaking change: architectural changes, API changes, schema changes, and similar major updates.
+
+* Y stands for a Minor version. Minor releases contain new features and functionality while maintaining backwards compatibility.
+
+* Z stands for a Patch version (also known as a z-stream release). Patch releases are used to addresses Common Vulnerabilities and Exposures (CVEs) and release bug fixes. New features and functionality are generally not released as part of a Patch release.
+
+== How versioning affects Service Mesh upgrades
+
+Depending on the version of the update you are making, the upgrade process is different.
+
+* *Patch updates* - Patch upgrades are managed by the Operator Lifecycle Manager (OLM); they happen automatically when you update your Operators.
+
+* *Minor upgrades* - Minor upgrades require both updating to the most recent {SMProductName} Operator version and manually modifying the `spec.version` value in your `ServiceMeshControlPlane` resources.
+
+* *Major upgrades* - Major upgrades require both updating to the most recent {SMProductName} Operator version and manually modifying the `spec.version` value in your `ServiceMeshControlPlane` resources. Because major upgrades may contain changes that are not backwards compatible, additional manual changes might be required.

modules/ossm-understanding-versions.adoc

@@ -1,5 +1,4 @@
 // Module included in the following assemblies:
-// * service_mesh/v1x/upgrading-ossm.adoc  ???
 // * service_mesh/v2x/upgrading-ossm.adoc
 // * service_mesh/v2x/ossm-troubleshooting.adoc
 
@@ -9,21 +8,17 @@
 
 In order to understand what version of {SMProductName} you have deployed on your system, you need to understand how each of the component versions is managed.
 
-The {SMProductName} 2.x Operator supports both v1x and v2x service meshes.
-
-* *Operator* version - The current Operator version is {SMProductVersion}. 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.
+* *Operator* version - The most current Operator version is {SMProductVersion}. The Operator version number only indicates the version of the currently installed Operator. Because the {SMProductName} Operator supports multiple versions of the control plane, the version of the Operator does not determine the version of your deployed `ServiceMeshControlPlane` resources.
 +
 [IMPORTANT]
 ====
-Upgrading to the latest Operator version does not automatically upgrade your control plane to the latest version.
+Upgrading to the latest Operator version automatically applies patch updates, but does not automatically upgrade your control plane to the latest minor version.
 ====
 +
-* *ServiceMeshControlPlane* version - The same Operator supports multiple versions of the service mesh control plane. The service mesh control plane version controls the architecture and configuration settings that are used to install and deploy {SMProductName}. To set or change the service mesh control plane version, you must deploy a new control plane. When you create the service mesh control plane you can select the version in one of two ways:
+* *ServiceMeshControlPlane* version - The `ServiceMeshControlPlane` version determines what version of {SMProductName} you are using. The value of the `spec.version` field in the `ServiceMeshControlPlane` resource controls the architecture and configuration settings that are used to install and deploy {SMProductName}. When you create the service mesh control plane you can set the version in one of two ways:
 
 ** To configure in the Form View, select the version from the *Control Plane Version* menu.
 
 ** 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, v2.0, and v2.1.
-
 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-upgrading-from-20-to-21.adoc

@@ -5,7 +5,7 @@
 [id="ossm-upgrading-from-20-21_{context}"]
 = Upgrading to {SMProductName} 2.1
 
-To upgrade {SMProductName}, you must update the version field of the {SMProductName} `ServiceMeshControlPlane` v2 resource. Then, once it's configured and applied, restart the application pods to update each sidecar proxy and its configuration.
+To upgrade {SMProductName}, you must update the version field of the {SMProductName} `ServiceMeshControlPlane` v2 resource. Then, once it is configured and applied, restart the application pods to update each sidecar proxy and its configuration.
 
 .Prerequisites
 

modules/ossm-upgrading-from-21-to-22.adoc

@@ -5,7 +5,7 @@
 [id="ossm-upgrading-from-21-22_{context}"]
 = Upgrading to {SMProductName} 2.2
 
-To upgrade {SMProductName}, you must update the version field of the {SMProductName} `ServiceMeshControlPlane` v2 resource. Then, once it's configured and applied, restart the application pods to update each sidecar proxy and its configuration.
+To upgrade {SMProductName}, you must update the version field of the {SMProductName} `ServiceMeshControlPlane` v2 resource. Then, once it is configured and applied, restart the application pods to update each sidecar proxy and its configuration.
 
 .Prerequisites
 

modules/ossm-upgrading-operator.adoc

@@ -4,25 +4,35 @@
 [id="ossm-upgrading-operator_{context}"]
 = Upgrading the Operators
 
+In order to keep your {SMProductShortName} patched with the latest security fixes, bug fixes, and software updates, you must keep your Operators updated. You initiate patch updates by upgrading your 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.
+The version of the Operator does *not* determine the version of your service mesh. The version of your deployed control plane determines your version of Service Mesh.
 ====
 
-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.
+Because the {SMProductName} Operator supports multiple versions of the control plane, updating the {SMProductName} Operator does _not_ update the `spec.version` value of your deployed `ServiceMeshControlPlane`. Also note that the `spec.version` value is a two digit number, for example 2.2, and that patch updates, for example 2.2.1, are not reflected in the SMCP version value.
+
+Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. The OLM runs by default in {product-title}. OLM queries for available Operators as well as upgrades for installed Operators.
+
+Whether or not you have to take action to upgrade your Operators depends on the settings you selected when installing them. When you installed each of your Operators, you selected an *Update Channel* and an *Approval Strategy*. The combination of these 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
+| |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 the 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.
 |====
+
+When you update your {SMProductName} Operator the Operator Lifecycle Manager (OLM) removes the old Operator pod and starts a new pod. Once the new Operator pod starts, the reconciliation process checks the `ServiceMeshControlPlane` (SMCP), and if there are updated container images available for any of the control plane components, it replaces those control plane pods with ones that use the new container images.
+
+When you upgrade the Kiali and {JaegerName} Operators, the OLM reconciliation process scans the cluster and upgrades the managed instances to the version of the new Operator. For example, if you update the {JaegerName} Operator from version 1.30.2 to version 1.34.1, the Operator scans for running instances of {JaegerShortName} and upgrades them to 1.34.1 as well.
+
+To stay on a particular patch version of {SMProductName}, you would need to disable automatic updates and remain on that specific version of the Operator.

service_mesh/v2x/upgrading-ossm.adoc

@@ -11,11 +11,13 @@ To access the most current features of {SMProductName}, upgrade to the current v
 ////
 The following include statements pull in the module files that comprise the assembly.
 ////
-include::modules/ossm-understanding-versions.adoc[leveloffset=+1]
+include::modules/ossm-understanding-versioning.adoc[leveloffset=+1]
+
+include::modules/ossm-understanding-versions.adoc[leveloffset=+2]
 
 include::modules/ossm-upgrade-considerations.adoc[leveloffset=+1]
 
-include::modules/ossm-upgrade-known-issues.adoc[leveloffset=+1]
+include::modules/ossm-upgrade-known-issues.adoc[leveloffset=+2]
 
 include::modules/ossm-upgrading-operator.adoc[leveloffset=+1]
 
@@ -26,8 +28,12 @@ endif::[]
 [id="upgrading-control-plane"]
 == Upgrading the Service Mesh control plane
 
+You must manually update the control plane for minor and major releases.
+
 include::modules/ossm-upgrade-21-22-changes.adoc[leveloffset=+2]
 
+For more information about migrating your extensions, refer to xref:../../service_mesh/v2x/ossm-extensions.adoc#ossm-extensions-migration-overview_ossm-extensions[Migrating from ServiceMeshExtension to WasmPlugin resources].
+
 include::modules/ossm-upgrading-from-21-to-22.adoc[leveloffset=+2]
 
 include::modules/ossm-upgrade-20-21-changes.adoc[leveloffset=+2]
@@ -39,4 +45,6 @@ include::modules/ossm-migrating-to-20.adoc[leveloffset=+1]
 [id="upgrading-data-plane"]
 == Upgrading the data plane
 
-include::modules/ossm-upgrade-apps-workloads.adoc[leveloffset=+1]
+You must restart your application pods and workloads to apply updates to the Envoy proxy or changes to proxy configuration.
+
+include::modules/ossm-upgrade-apps-workloads.adoc[leveloffset=+2]