Merge pull request #38184 from rh-tokeefe/OSSMDOC-210

OSSMDOC-210: Upgrading service mesh from 2.0 to 2.1

Author: abrennan89

service_mesh/v2x/upgrading-ossm-to-2-1.adoc

@@ -0,0 +1,108 @@
+[id="ossm-upgrade-to-2-1"]
+= Upgrading {ProductName} from version 2.0 to version 2.1
+include::modules/ossm-document-attributes.adoc[]
+:context: oossm-upgrading-to-2-1
+
+toc::[]
+
+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.
+
+[id="ossm-upgrading-upgrade-2-1_{context}"]
+== Upgrading to {ProductName} 2.1
+
+To upgrade {ProductName}, you must update the version field of the {ProductName} `ServiceMeshControlPlane` v2 resource. Then, once it's configured and applied, restart the application pods to update each sidecar proxy and its configuration.
+
+.Prerequisites
+
+* You are running {product-title} 4.6 or later.
+* You have the {ProductName} version 2.1.0 operator. If the *automatic* upgrade path is enabled, the operator automatically downloads the latest information. However, there are steps you must take to use the features in {ProductName} version 2.1.
+* You must upgrade from {ProductName} 2.0 to 2.1. You cannot upgrade `ServiceMeshControlPlane` from 1.1 to 2.1 directly.
+
+.Procedure
+
+. Switch to the project that contains your `ServiceMeshControlPlane` resource.  In this example, `istio-system` is the name of the control plane project.
++
+[source,terminal]
+----
+$ oc project istio-system
+----
+
+. Check your v2 `ServiceMeshControlPlane` resource configuration to make sure it is valid.
++
+.. Run the following command to view your `ServiceMeshControlPlane` resource as a v2 resource.
++
+[source,terminal]
+----
+$ oc get smcp -o yaml
+----
+
+TIP: Back up your control plane configuration.
+
+. Update the `.spec.version` field from v2.0 to v2.1, and apply the configuration.
++
+If you see the following message, 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,terminal]
+----
+spec:
+  policy:
+    type: Istoid
+  telemetry:
+    type: Istiod
+  version: v2.1
+----
++
+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.
++
+.. Click *Operators* -> *Installed Operators*.
+.. Find your `ServiceMeshControlPlane` instance.
+.. Select *YAML view* and update text of the YAML file, as shown in the previous example.
+.. Click *Save*.
+
+[id="ossm-upgrading-differences-arch_{context}"]
+== Changes from prior release
+
+This upgrade introduces the following architectural and behavioral changes.
+
+.Architecture changes
+
+Mixer has been completely removed in {ProductName} 2.1. Upgrading from a {ProductName} 2.0.x release to 2.1 will be blocked if Mixer is enabled.
+
+[id="ossm-upgrading-differences-behavior_{context}"]
+.Behavioral changes
+
+* `AuthorizationPolicy` updates
+** With the PROXY protocol, if you're using `ipBlocks` and `notIpBlocks` to specify remote IP addresses, update the configuration to use `remoteIpBlocks` and `notRemoteIpBlocks` instead.
+** Added support for nested JSON Web Token (JWT) claims
+* `EnvoyFilter` breaking changes
+** Must use `typed_config`
+** 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.
+====
+
+[id="ossm-upgrading-mig-apps_{context}"]
+== Next steps for migrating your applications and workflows
+
+To complete the migration, restart all of the application pods in the mesh to upgrade the Envoy sidecar proxies and their configuration.
+
+To perform a rolling update of a deployment use the following command:
+
+[source,terminal]
+----
+$ oc rollout restart <deployment>
+----
+
+You must perform a rolling update for all applications that make up the mesh.