OSSM-8264

Author: shreyasiddhartha

modules/ossm-migrating-read-me-new-operator.adoc

@@ -25,9 +25,26 @@ Basing {SMProduct} 3 directly on Istio ensures that {SMProduct} 3 supports users
 
 {SMProduct} 3 uses an Operator that is maintained upstream as the Sail Operator in the *istio-ecosystem* organization on GitHub. The {SMProduct} 3 Operator is smaller in scope and includes significant changes from the Operator used in {SMProduct} 2:
 
-* The `Istio` resource replaces the `ServiceMeshControlPlane` resource.
-* The `IstioCNI` resource manages the Istio Container Network Interface (CNI).
+* The `{istio}` resource replaces the `ServiceMeshControlPlane` resource.
+* The `IstioCNI` resource manages the {istio} Container Network Interface (CNI).
 * Red{nbsp}Hat OpenShift Observability components are installed and configured separately.
 
+[id="ossm-about-operator-component-versioning_{context}"]
+== About Operator and component versioning
+
+All {product-title} Operators use versioning and manage at least one underlying component (operand), which is often versioned independently through a custom resource definition (CRD).
+
+In {SMProduct} 2, the `ServiceMeshControlPlane` resource managed multiple operands, including {istio}, Kiali, and Jaeger. Each component maintained its own version containing the following three levels of versioning:
+
+* The Operator version
+* The `ServiceMeshControlPlane` version
+* The individual component versions
+
+For example, the {SMProduct} 2.6 Operator managed the 2.6 version of the control plane, which included {istio} 1.20, Kiali 1.73, and other component versions. Each Operator version also supported multiple control plane versions. The {SMProduct} 2.6 Operator supported versions 2.4, 2.5, and 2.6 of the control plane.
+
+{SMProduct} 3 simplifies versioning by limiting Operator management to the {istio} resource. The {istio} resource is responsible only for the {istio} component and does not manage Kiali or other components. So, the {istio} resource specifies only the {istio} component version.
+
+Each {SMProduct} release supports the latest available {istio} version for that Operator version. For example, {SMProduct} 3.0.0 supports {istio} 1.24.0. While the Operator might contain other {istio} versions to support upgrades, product support, including patches for Common Vulnerabilities and Exposures (CVEs), covers only the latest {istio} version in a given Operator release. For each Operator release, update to the most recent {istio} version available.
+
 //Note for later: update "Red{nbsp}Hate OpenShift Observability" with appropriate attribute when that attribute has been added to the Service Mesh stand alone _attributes file.
 //Note that as of 11/18/2024, no attributes in OCP main _attributes file use Red{nbsp}Hat. OCP main _attributes are not in line with current style.

modules/ossm-migrating-read-me-new-resources.adoc

@@ -9,32 +9,39 @@
 [id="ossm-migrating-read-me-new-resources_{context}"]
 = New resources in {SMProduct} 3
 
-{SMProductName} 3 uses two new resources:
+{SMProductName} 3 uses the following two new resources:
 
-* `Istio` resource
-* `IstioCNI` resource
+* `{istio}`
+* `IstioCNI`
 
 [id="ossm-istio-resource-replaces-smcp_{context}"]
 == The Istio resource replaces the ServiceMeshControlPlane resource
 
-{SMProduct} 2 uses a resource called `ServiceMeshControlPlane` to configure Istio. In {SMProduct} 3, the `ServiceMeshControlPlane` resource is replaced with a resource called `Istio`.
+{SMProduct} 2 uses a resource called `ServiceMeshControlPlane` to configure {istio}. In {SMProduct} 3, the `ServiceMeshControlPlane` resource is replaced with a resource called `{istio}`.
 
-The `Istio` resource contains a `spec.values` field that derives its schema from Istio's Helm chart values. This means that configuration examples from the community Istio documentation can often be applied directly to the {SMProduct} 3 `Istio` resource.
+The `{istio}` resource contains a `spec.values` field that derives its schema from {istio}'s Helm chart values. This means that configuration examples from the community {istio} documentation can often be applied directly to the {SMProduct} 3 `{istio}` resource.
 
-The `Istio` resource provides an additional validation schema enabling the ability to explore the resource running the following the {ocp-short-name} command line interface (CLI) command:
+You can view an additional validation schema of the `{istio}` resource by running the following command:
 
 [source,terminal]
 ----
 $ oc explain istios.spec.values
 ----
 
-//Note that there might be an attribute for OpenShift CLI. Check main _attributes file, and if there is an attribute for it, add it to list for service-mesh-docs-main _attributes file.
+[id="ossm-about-istio-control-plane-versioning_{context}"]
+== About Istio control plane versioning
+
+In {SMProduct} 2.6 and earlier, the `version` field in the `ServiceMeshControlPlane` resource specified the control plane version. The `version` field accepted only minor versions, such as `v2.5` or `v2.6`. The Operator automatically applied new patch versions, such as 2.6.1, without requiring changes to the resource.
+
+{SMProduct} 3.0 introduces the `{istio}` resource to manage {istio} control planes. This resource also includes a `version` field, but it uses {istio} versioning instead of {SMProduct} versions. The field accepts specific patch versions, such as `v1.24.1`, which the Operator maintains without applying automatic updates.
+
+To enable automatic patch updates, use a version in the format `v1.24-latest`. This instructs the Operator to keep the {istio} control plane updated with the latest available patch release of {istio} 1.24.
 
 [id="ossm-new-resource-istiocni_{context}"]
 == New resource: IstioCNI
 
-The Istio Container Network Interface (CNI) node agent is used to configure traffic redirection for pods in the mesh. It runs as a daemon set, on every node, with elevated privileges.
+The {istio} Container Network Interface (CNI) node agent is used to configure traffic redirection for pods in the mesh. It runs as a daemon set, on every node, with elevated privileges.
 
-In {SMProduct} 2, the Operator deployed an Istio CNI instance for each minor version of Istio present in the cluster, and pods were automatically annotated during sidecar injection so they picked up the correct Istio CNI. While this meant that the management of Istio CNI was mostly hidden from you, it obscured the fact that the Istio CNI agent has an independent lifecycle from the Istio control plane and, in some cases, the Istio CNI agent must be be upgraded separately.
+In {SMProduct} 2, the Operator deployed an {istio} CNI instance for each minor version of {istio} present in the cluster, and pods were automatically annotated during sidecar injection so they picked up the correct {istio} CNI. The {istio} CNI agent has an independent lifecycle from the {istio} control plane and, in some cases, you must upgrade the {istio} CNI agent separately.
 
-For these reasons, the {SMProduct} 3 Operator manages the Istio CNI node agent with a separate resource called `IstioCNI`. A single instance of this resource is shared by all Istio control planes, which are managed by `Istio` resources.
+For these reasons, the {SMProduct} 3 Operator manages the {istio} CNI node agent with a separate resource called `IstioCNI`. A single instance of this resource is shared by all {istio} control planes, which are managed by `{istio}` resources.