Merge pull request #49364 from JStickler/OSSMDOC-628A

JStickler · web-flow · commit 3340560ae8d9 · 2022-09-15T12:07:49.000-04:00
OSSMDOC-628: make SMCP upgrade generic.
diff --git a/modules/ossm-understanding-versioning.adoc b/modules/ossm-understanding-versioning.adoc
@@ -20,4 +20,4 @@ Depending on the version of the update you are making, the upgrade process is di
 
 * *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.
+* *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 can contain changes that are not backwards compatible, additional manual changes might be required.
diff --git a/modules/ossm-upgrade-20-21-changes.adoc b/modules/ossm-upgrade-20-21-changes.adoc
@@ -11,6 +11,29 @@ Upgrading the control plane from version 2.0 to 2.1 introduces the following arc
 
 Mixer has been completely removed in {SMProductName} 2.1. Upgrading from a {SMProductName} 2.0.x release to 2.1 will be blocked if Mixer is enabled.
 
+If you see the following message when upgrading from v2.0 to v2.1, update the existing `Mixer` type to `Istiod` type in the existing Control Plane spec before you update the `.spec.version` field:
+
+[source,text]
+----
+An error occurred
+admission webhook smcp.validation.maistra.io denied the request: [support for policy.type "Mixer" and policy.Mixer options have been removed in v2.1, please use another alternative, support for telemetry.type "Mixer" and telemetry.Mixer options have been removed in v2.1, please use another alternative]”
+----
+
+For example:
+
+[source,yaml, subs="attributes,verbatim"]
+----
+apiVersion: maistra.io/v2
+kind: ServiceMeshControlPlane
+spec:
+  policy:
+    type: Istiod
+  telemetry:
+    type: Istiod
+  version: v{MaistraVersion}
+----
+
+
 [id="ossm-upgrading-differences-behavior_{context}"]
 .Behavioral changes
 
@@ -22,8 +45,3 @@ Mixer has been completely removed in {SMProductName} 2.1. Upgrading from a {SMPr
 ** xDS v2 is no longer supported
 ** Deprecated filter names
 * Older versions of proxies may report 503 status codes when receiving 1xx or 204 status codes from newer proxies.
-
-[NOTE]
-====
-Red Hat is unable to support `EnvoyFilter` configuration except where explicitly documented. This is due to tight coupling with the underlying Envoy APIs, meaning that backward compatibility cannot be maintained.
-====
diff --git a/modules/ossm-upgrade-known-issues.adoc b/modules/ossm-upgrade-known-issues.adoc
@@ -7,7 +7,7 @@
 
 Known issues that may affect your upgrade include:
 
-* {SMProductName} does not support the use of `EnvoyFilter` configuration except where explicitly documented. If you are using Envoy Filters, and the configuration generated by Istio has changed due to the new version of Envoy introduced by upgrading your `ServiceMeshControlPlane`, that has the potential to break any `EnvoyFilter` you may have implemented.
+* {SMProductName} does not support the use of `EnvoyFilter` configuration except where explicitly documented. This is due to tight coupling with the underlying Envoy APIs, meaning that backward compatibility cannot be maintained. If you are using Envoy Filters, and the configuration generated by Istio has changed due to the lastest version of Envoy introduced by upgrading your `ServiceMeshControlPlane`, that has the potential to break any `EnvoyFilter` you may have implemented.
 
 * https://issues.redhat.com/browse/OSSM-1505[OSSM-1505] `ServiceMeshExtension` does not work with {product-title} version 4.11. Because `ServiceMeshExtension` has been deprecated in {SMProductName} 2.2, this known issue will not be fixed and you must migrate your extensions to `WasmPluging`
 
diff --git a/modules/ossm-upgrading-from-20-to-21.adoc b/modules/ossm-upgrading-from-20-to-21.adoc
diff --git a/modules/ossm-upgrading-smcp.adoc b/modules/ossm-upgrading-smcp.adoc
@@ -2,16 +2,15 @@
 // * service_mesh/v2x/upgrading-ossm.adoc
 
 :_content-type: PROCEDURE
-[id="ossm-upgrading-from-21-22_{context}"]
-= Upgrading to {SMProductName} 2.2
+[id="ossm-upgrading-smcp_{context}"]
+= Upgrading the Service Mesh control plane
 
 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
 
 * You are running {product-title} 4.9 or later.
-* You have the {SMProductName} version 2.2.x operator.
-* You cannot upgrade your `ServiceMeshControlPlane` from 1.1 to 2.2 directly.  Because of possibly breaking changes at each stage, you must migrate from 1.1 to 2.0, then upgrade from 2.0 to 2.1, then upgrade 2.1 to 2.2.
+* You have the latest {SMProductName} Operator.
 
 .Procedure
 
@@ -22,7 +21,7 @@ To upgrade {SMProductName}, you must update the version field of the {SMProductN
 $ oc project istio-system
 ----
 
-. Check your v2 `ServiceMeshControlPlane` resource configuration to make sure it is valid.
+. Check your v2 `ServiceMeshControlPlane` resource configuration to verify it is valid.
 +
 .. Run the following command to view your `ServiceMeshControlPlane` resource as a v2 resource.
 +
@@ -36,18 +35,18 @@ $ oc get smcp -o yaml
 Back up your control plane configuration.
 ====
 
-. Update the `.spec.version` field from v2.1 to v2.2, and apply the configuration.
+. Update the `.spec.version` field and apply the configuration.
 +
 For example:
 +
-[source,terminal]
+[source,yaml, subs="attributes,verbatim"]
 ----
 apiVersion: maistra.io/v2
 kind: ServiceMeshControlPlane
 metadata:
   name: basic
 spec:
-  version: v2.2
+  version: v{MaistraVersion}
 ----
 +
 Alternatively, instead of using the command line, you can use the web console to edit the control plane. In the {product-title} web console, click *Project* and select the project name you just entered.
diff --git a/service_mesh/v2x/upgrading-ossm.adoc b/service_mesh/v2x/upgrading-ossm.adoc
@@ -26,27 +26,28 @@ For more information about upgrading Operators, refer to the xref:../../operator
 endif::[]
 
 [id="upgrading-control-plane"]
-== Upgrading the Service Mesh control plane
+== Upgrading the control plane
 
 You must manually update the control plane for minor and major releases. The community Istio project recommends canary upgrades, {SMProductName} only supports in-place upgrades. {SMProductName} requires that you upgrade from each minor release to the next minor release in sequence. For example, you must upgrade from version 2.0 to version 2.1, and then upgrade to version 2.2. You cannot update from {SMProductName} 2.0 to 2.2 directly.
 
 When you upgrade the service mesh control plane, all Operator managed resources, for example gateways, are also upgraded.
 
+Although you can deploy multiple versions of the control plane in the same cluster, {SMProductName} does not support canary upgrades of the service mesh. That is, you can have different SCMP resources with different values for `spec.version`, but they cannot be managing the same mesh.
+
 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]
 
-include::modules/ossm-upgrading-from-20-to-21.adoc[leveloffset=+2]
+include::modules/ossm-upgrading-smcp.adoc[leveloffset=+2]
 
-include::modules/ossm-migrating-to-20.adoc[leveloffset=+1]
+include::modules/ossm-migrating-to-20.adoc[leveloffset=+2]
 
 [id="upgrading-data-plane"]
 == Upgrading the data plane
 
-You must restart your application pods and workloads to apply updates to the Envoy proxy or changes to proxy configuration.
+Your data plane will still function after you have upgraded the control plane. But in order to apply updates to the Envoy proxy and any changes to the proxy configuration, you must restart your application pods and workloads.
 
 include::modules/ossm-upgrade-apps-workloads.adoc[leveloffset=+2]

Original file line number	Diff line number	Diff line change
`@@ -20,4 +20,4 @@ Depending on the version of the update you are making, the upgrade process is di`
`20`	`20`
`21`	`21`	* 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.
`22`	`22`
`23`		-* 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.
	`23`	+* 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 can contain changes that are not backwards compatible, additional manual changes might be required.