--- title: Upgrading Service Mesh --- # Upgrading Service Mesh {#upgrading-ossm} To access the most current features of Red Hat OpenShift Service Mesh, upgrade to the current version, 2.6.11. ## Understanding versioning {#ossm-versioning_ossm-upgrade} 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 {#_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 Red Hat OpenShift Service Mesh Operator version and manually modifying the `spec.version` value in your `ServiceMeshControlPlane` resources. - **Major upgrades** - Major upgrades require both updating to the most recent Red Hat OpenShift Service Mesh 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. ### Understanding Service Mesh versions {#ossm-versions_ossm-upgrade} In order to understand what version of Red Hat OpenShift Service Mesh you have deployed on your system, you need to understand how each of the component versions is managed. - **Operator** version - The most current Operator version is 2.6.11. The Operator version number only indicates the version of the currently installed Operator. Because the Red Hat OpenShift Service Mesh Operator supports multiple versions of the Service Mesh control plane, the version of the Operator does not determine the version of your deployed `ServiceMeshControlPlane` resources. > [!IMPORTANT] > Upgrading to the latest Operator version automatically applies patch updates, but does not automatically upgrade your Service Mesh control plane to the latest minor version. - **ServiceMeshControlPlane** version - The `ServiceMeshControlPlane` version determines what version of Red Hat OpenShift Service Mesh 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 Red Hat OpenShift Service Mesh. 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. Operator Lifecycle Manager (OLM) does not manage Service Mesh control plane upgrades, so the version number for your Operator and `ServiceMeshControlPlane` (SMCP) may not match, unless you have manually upgraded your SMCP. ## Upgrade considerations {#ossm-upgrade-considerations_ossm-upgrade} 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 Red Hat OpenShift Service Mesh 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` (Red Hat OpenShift Service Mesh) - `kiali.io/` (Kiali) - `jaegertracing.io/` (Red Hat OpenShift Distributed Tracing Platform (Jaeger)) - `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. ### Known issues that may affect upgrade {#ossm-upgrade-known-issues_ossm-upgrade} Known issues that may affect your upgrade include: - When upgrading an Operator, custom configurations for Jaeger or Kiali might be reverted. Before upgrading an Operator, note any custom configuration settings for the Jaeger or Kiali objects in the Service Mesh production deployment so that you can recreate them. - Red Hat OpenShift Service Mesh 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. - [OSSM-1505](https://issues.redhat.com/browse/OSSM-1505) `ServiceMeshExtension` does not work with OpenShift Container Platform version 4.11. Because `ServiceMeshExtension` has been deprecated in Red Hat OpenShift Service Mesh 2.2, this known issue will not be fixed and you must migrate your extensions to `WasmPluging` - [OSSM-1396](https://issues.redhat.com/browse/OSSM-1396) If a gateway resource contains the `spec.externalIPs` setting, rather than being recreated when the `ServiceMeshControlPlane` is updated, the gateway is removed and never recreated. - [OSSM-1052](https://issues.redhat.com/browse/OSSM-1052) When configuring a Service `ExternalIP` for the ingressgateway in the Service Mesh control plane, the service is not created. The schema for the SMCP is missing the parameter for the service. Workaround: Disable the gateway creation in the SMCP spec and manage the gateway deployment entirely manually (including Service, Role and RoleBinding). ## Upgrading the Operators {#ossm-upgrading-operator_ossm-upgrade} In order to keep your Service Mesh 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 version of your deployed Service Mesh control plane determines your version of Service Mesh. Because the Red Hat OpenShift Service Mesh Operator supports multiple versions of the Service Mesh control plane, updating the Red Hat OpenShift Service Mesh 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 OpenShift Container Platform. 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**
Versioned channel "Stable" or "Preview" Channel
Automatic 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 Red Hat OpenShift Service Mesh 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 Service Mesh control plane components, it replaces those Service Mesh control plane pods with ones that use the new container images. When you upgrade the Kiali and Red Hat OpenShift Distributed Tracing Platform (Jaeger) 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 Red Hat OpenShift Distributed Tracing Platform (Jaeger) Operator from version 1.30.2 to version 1.34.1, the Operator scans for running instances of Distributed Tracing Platform (Jaeger) and upgrades them to 1.34.1 as well. To stay on a particular patch version of Red Hat OpenShift Service Mesh, you would need to disable automatic updates and remain on that specific version of the Operator. For more information about upgrading Operators, refer to the [Operator Lifecycle Manager](/openshift-docs-markdown/operators/admin/olm-upgrading-operators) documentation. ## Upgrading the control plane {#upgrading-control-plane} You must manually update the control plane for minor and major releases. The community Istio project recommends canary upgrades, Red Hat OpenShift Service Mesh only supports in-place upgrades. Red Hat OpenShift Service Mesh 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 Red Hat OpenShift Service Mesh 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, Red Hat OpenShift Service Mesh 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. For more information about migrating your extensions, refer to [Migrating from ServiceMeshExtension to WasmPlugin resources](/openshift-docs-markdown/service_mesh/v2x/ossm-extensions#ossm-extensions-migration-overview_ossm-extensions). ### Upgrade changes from version 2.5 to version 2.6 {#ossm-upgrade-25-26-changes_ossm-upgrade} #### Red Hat OpenShift Distributed Tracing Platform (Jaeger) default setting change {#_jaegername_default_setting_change} This release disables Red Hat OpenShift Distributed Tracing Platform (Jaeger) by default for new instances of the `ServiceMeshControlPlane` resource. When updating existing instances of the `ServiceMeshControlPlane` resource to Red Hat OpenShift Service Mesh version 2.6, Distributed Tracing Platform (Jaeger) remains enabled by default. Red Hat OpenShift Service Mesh 2.6 is the last release that includes support for Red Hat OpenShift Distributed Tracing Platform (Jaeger) and OpenShift Elasticsearch Operator. Both Distributed Tracing Platform (Jaeger) and OpenShift Elasticsearch Operator will be removed in the next release. If you are currently using Distributed Tracing Platform (Jaeger) and OpenShift Elasticsearch Operator, you must migrate to Red Hat OpenShift Distributed Tracing Platform and Red Hat build of OpenTelemetry. #### Envoy sidecar container default setting change {#_envoy_sidecar_container_default_setting_change} To enhance pod startup times, Istio now includes a `startupProbe` in sidecar containers by default. The pod’s readiness probes do not start until the Envoy sidecar has started. ### Upgrade changes from version 2.4 to version 2.5 {#ossm-upgrade-24-25-changes_ossm-upgrade} #### Istio OpenShift Routing (IOR) default setting change {#_istio_openshift_routing_ior_default_setting_change} The default setting for Istio OpenShift Routing (IOR) has changed. The setting is now disabled by default. You can use IOR by setting the `enabled` field to `true` in the `spec.gateways.openshiftRoute` specification of the `ServiceMeshControlPlane` resource. ```yaml apiVersion: maistra.io/v2 kind: ServiceMeshControlPlane spec: gateways: openshiftRoute: enabled: true ``` #### Istio proxy concurrency configuration enhancement {#_istio_proxy_concurrency_configuration_enhancement} For consistency across deployments, Istio now configures the `concurrency` parameter based on the CPU limit allocated to the proxy container. For example, a limit of 2500m would set the `concurrency` parameter to 3. If you set the `concurrency` parameter to a value, Istio uses that value to configure how many threads the proxy runs instead of using the CPU limit. Previously, the default setting for the parameter was 2. ### Upgrade changes from version 2.3 to version 2.4 {#ossm-upgrade-23-24-changes_ossm-upgrade} Upgrading the Service Mesh control plane from version 2.3 to 2.4 introduces the following behavioral changes: - Support for Istio OpenShift Routing (IOR) has been deprecated. IOR functionality is still enabled, but it will be removed in a future release. - The following cipher suites are no longer supported, and were removed from the list of ciphers used in client and server side TLS negotiations. - ECDHE-ECDSA-AES128-SHA - ECDHE-RSA-AES128-SHA - AES128-GCM-SHA256 - AES128-SHA - ECDHE-ECDSA-AES256-SHA - ECDHE-RSA-AES256-SHA - AES256-GCM-SHA384 - AES256-SHA Applications that require access to services that use one of these cipher suites will fail to connect when the proxy initiates a TLS connection. ### Upgrade changes from version 2.2 to version 2.3 {#ossm-upgrade-22-23-changes_ossm-upgrade} Upgrading the Service Mesh control plane from version 2.2 to 2.3 introduces the following behavioral changes: - This release requires use of the `WasmPlugin` API. Support for the `ServiceMeshExtension` API, which was deprecated in 2.2, has now been removed. If you attempt to upgrade while using the `ServiceMeshExtension` API, then the upgrade fails. ### Upgrade changes from version 2.1 to version 2.2 {#ossm-upgrade-21-22-changes_ossm-upgrade} Upgrading the Service Mesh control plane from version 2.1 to 2.2 introduces the following behavioral changes: - The `istio-node` DaemonSet is renamed to `istio-cni-node` to match the name in upstream Istio. - Istio 1.10 updated Envoy to send traffic to the application container using `eth0` rather than `lo` by default. - This release adds support for the `WasmPlugin` API and deprecates the `ServiceMeshExtension` API. ### Upgrade changes from version 2.0 to version 2.1 {#ossm-upgrade-20-21-changes_ossm-upgrade} Upgrading the Service Mesh control plane from version 2.0 to 2.1 introduces the following architectural and behavioral changes. **Architecture changes** Mixer has been completely removed in Red Hat OpenShift Service Mesh 2.1. Upgrading from a Red Hat OpenShift Service Mesh 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: ```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: ```yaml apiVersion: maistra.io/v2 kind: ServiceMeshControlPlane spec: policy: type: Istiod telemetry: type: Istiod version: v2.6 ``` **Behavioral changes** - `AuthorizationPolicy` updates: - With the PROXY protocol, if you are 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. ### Upgrading the Service Mesh control plane {#ossm-upgrading-smcp_ossm-upgrade} To upgrade Red Hat OpenShift Service Mesh, you must update the version field of the Red Hat OpenShift Service Mesh `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 OpenShift Container Platform 4.9 or later. - You have the latest Red Hat OpenShift Service Mesh Operator. **Procedure** 1. Switch to the project that contains your `ServiceMeshControlPlane` resource. In this example, `istio-system` is the name of the Service Mesh control plane project. ```terminal $ oc project istio-system ``` 2. Check your v2 `ServiceMeshControlPlane` resource configuration to verify it is valid. 1. Run the following command to view your `ServiceMeshControlPlane` resource as a v2 resource. ```terminal $ oc get smcp -o yaml ``` > [!TIP] > Back up your Service Mesh control plane configuration. 3. Update the `.spec.version` field and apply the configuration. For example: ```yaml apiVersion: maistra.io/v2 kind: ServiceMeshControlPlane metadata: name: basic spec: version: v2.6 ``` Alternatively, instead of using the command line, you can use the web console to edit the Service Mesh control plane. In the OpenShift Container Platform web console, click **Project** and select the project name you just entered. 1. Click **Ecosystem** → **Installed Operators**. 2. Find your `ServiceMeshControlPlane` instance. 3. Select **YAML view** and update text of the YAML file, as shown in the previous example. 4. Click **Save**. ### Migrating Red Hat OpenShift Service Mesh from version 1.1 to version 2.0 {#ossm-migrating-to-20_ossm-upgrade} Upgrading from version 1.1 to 2.0 requires manual steps that migrate your workloads and application to a new instance of Red Hat OpenShift Service Mesh running the new version. **Prerequisites** - You must upgrade to OpenShift Container Platform 4.7. before you upgrade to Red Hat OpenShift Service Mesh 2.0. - You must have Red Hat OpenShift Service Mesh version 2.0 operator. If you selected the **automatic** upgrade path, the operator automatically downloads the latest information. However, there are steps you must take to use the features in Red Hat OpenShift Service Mesh version 2.0. #### Upgrading Red Hat OpenShift Service Mesh {#ossm-migrating_ossm-upgrade} To upgrade Red Hat OpenShift Service Mesh, you must create an instance of Red Hat OpenShift Service Mesh `ServiceMeshControlPlane` v2 resource in a new namespace. Then, once it is configured, move your microservice applications and workloads from your old mesh to the new service mesh. **Procedure** 1. Check your v1 `ServiceMeshControlPlane` resource configuration to make sure it is valid. 1. Run the following command to view your `ServiceMeshControlPlane` resource as a v2 resource. ```terminal $ oc get smcp -o yaml ``` 2. Check the `spec.techPreview.errored.message` field in the output for information about any invalid fields. 3. If there are invalid fields in your v1 resource, the resource is not reconciled and cannot be edited as a v2 resource. All updates to v2 fields will be overridden by the original v1 settings. To fix the invalid fields, you can replace, patch, or edit the v1 version of the resource. You can also delete the resource without fixing it. After the resource has been fixed, it can be reconciled, and you can to modify or view the v2 version of the resource. 4. To fix the resource by editing a file, use `oc get` to retrieve the resource, edit the text file locally, and replace the resource with the file you edited. ```terminal $ oc get smcp.v1.maistra.io > smcp-resource.yaml #Edit the smcp-resource.yaml file. ``` ```terminal $ oc replace -f smcp-resource.yaml ``` 5. To fix the resource using patching, use `oc patch`. ```terminal $ oc patch smcp.v1.maistra.io --type json --patch '[{"op": "replace","path":"/spec/path/to/bad/setting","value":"corrected-value"}]' ``` 6. To fix the resource by editing with command-line tools, use `oc edit`. ```terminal $ oc edit smcp.v1.maistra.io ``` 2. Back up your Service Mesh control plane configuration. Switch to the project that contains your `ServiceMeshControlPlane` resource. In this example, `istio-system` is the name of the Service Mesh control plane project. ```terminal $ oc project istio-system ``` 3. Enter the following command to retrieve the current configuration. Your is specified in the metadata of your `ServiceMeshControlPlane` resource, for example `basic-install` or `full-install`. ```terminal $ oc get servicemeshcontrolplanes.v1.maistra.io -o yaml > .v1.yaml ``` 4. Convert your `ServiceMeshControlPlane` to a v2 control plane version that contains information about your configuration as a starting point. ```terminal $ oc get smcp -o yaml > .v2.yaml ``` 5. Create a project. In the OpenShift Container Platform console Project menu, click `New Project` and enter a name for your project, `istio-system-upgrade`, for example. Or, you can run this command from the CLI. ```terminal $ oc new-project istio-system-upgrade ``` 6. Update the `metadata.namespace` field in your v2 `ServiceMeshControlPlane` with your new project name. In this example, use `istio-system-upgrade`. 7. Update the `version` field from 1.1 to 2.0 or remove it in your v2 `ServiceMeshControlPlane`. 8. Create a `ServiceMeshControlPlane` in the new namespace. On the command line, run the following command to deploy the control plane with the v2 version of the `ServiceMeshControlPlane` that you retrieved. In this example, replace `<smcp_name.v2> `with the path to your file. ```terminal $ oc create -n istio-system-upgrade -f .v2.yaml ``` Alternatively, you can use the console to create the Service Mesh control plane. In the OpenShift Container Platform web console, click **Project**. Then, select the project name you just entered. 1. Click **Ecosystem** → **Installed Operators**. 2. Click **Create ServiceMeshControlPlane**. 3. Select **YAML view** and paste text of the YAML file you retrieved into the field. Check that the `apiVersion` field is set to `maistra.io/v2` and modify the `metadata.namespace` field to use the new namespace, for example `istio-system-upgrade`. 4. Click **Create**. #### Configuring the 2.0 ServiceMeshControlPlane {#ossm-migrating-smcp_ossm-upgrade} The `ServiceMeshControlPlane` resource has been changed for Red Hat OpenShift Service Mesh version 2.0. After you created a v2 version of the `ServiceMeshControlPlane` resource, modify it to take advantage of the new features and to fit your deployment. Consider the following changes to the specification and behavior of Red Hat OpenShift Service Mesh 2.0 as you are modifying your `ServiceMeshControlPlane` resource. You can also refer to the Red Hat OpenShift Service Mesh 2.0 product documentation for new information to features you use. The v2 resource must be used for Red Hat OpenShift Service Mesh 2.0 installations. ##### Architecture changes {#ossm-migrating-differences-arch_ossm-upgrade} The architectural units used by previous versions have been replaced by Istiod. In 2.0 the Service Mesh control plane components Mixer, Pilot, Citadel, Galley, and the sidecar injector functionality have been combined into a single component, Istiod. Although Mixer is no longer supported as a control plane component, Mixer policy and telemetry plugins are now supported through WASM extensions in Istiod. Mixer can be enabled for policy and telemetry if you need to integrate legacy Mixer plugins. Secret Discovery Service (SDS) is used to distribute certificates and keys to sidecars directly from Istiod. In Red Hat OpenShift Service Mesh version 1.1, secrets were generated by Citadel, which were used by the proxies to retrieve their client certificates and keys. ##### Annotation changes {#ossm-migrating-differences-annotation_ossm-upgrade} The following annotations are no longer supported in v2.0. If you are using one of these annotations, you must update your workload before moving it to a v2.0 Service Mesh control plane. - `sidecar.maistra.io/proxyCPULimit` has been replaced with `sidecar.istio.io/proxyCPULimit`. If you were using `sidecar.maistra.io` annotations on your workloads, you must modify those workloads to use `sidecar.istio.io` equivalents instead. - `sidecar.maistra.io/proxyMemoryLimit` has been replaced with `sidecar.istio.io/proxyMemoryLimit` - `sidecar.istio.io/discoveryAddress` is no longer supported. Also, the default discovery address has moved from `pilot..svc:15010` (or port 15011, if mtls is enabled) to `istiod-..svc:15012`. - The health status port is no longer configurable and is hard-coded to 15021. \* If you were defining a custom status port, for example, `status.sidecar.istio.io/port`, you must remove the override before moving the workload to a v2.0 Service Mesh control plane. Readiness checks can still be disabled by setting the status port to `0`. - Kubernetes Secret resources are no longer used to distribute client certificates for sidecars. Certificates are now distributed through Istiod’s SDS service. If you were relying on mounted secrets, they are longer available for workloads in v2.0 Service Mesh control planes. ##### Behavioral changes {#ossm-migrating-differences-behavior_ossm-upgrade} Some features in Red Hat OpenShift Service Mesh 2.0 work differently than they did in previous versions. - The readiness port on gateways has moved from `15020` to `15021`. - The target host visibility includes VirtualService, as well as ServiceEntry resources. It includes any restrictions applied through Sidecar resources. - Automatic mutual TLS is enabled by default. Proxy to proxy communication is automatically configured to use mTLS, regardless of global PeerAuthentication policies in place. - Secure connections are always used when proxies communicate with the Service Mesh control plane regardless of `spec.security.controlPlane.mtls` setting. The `spec.security.controlPlane.mtls` setting is only used when configuring connections for Mixer telemetry or policy. ##### Migration details for unsupported resources {#ossm-migrating-unsupported-resources_ossm-upgrade} **Policy (authentication.istio.io/v1alpha1)** Policy resources must be migrated to new resource types for use with v2.0 Service Mesh control planes, PeerAuthentication and RequestAuthentication. Depending on the specific configuration in your Policy resource, you may have to configure multiple resources to achieve the same effect. **Mutual TLS** Mutual TLS enforcement is accomplished using the `security.istio.io/v1beta1` PeerAuthentication resource. The legacy `spec.peers.mtls.mode` field maps directly to the new resource’s `spec.mtls.mode` field. Selection criteria has changed from specifying a service name in `spec.targets[x].name` to a label selector in `spec.selector.matchLabels`. In PeerAuthentication, the labels must match the selector on the services named in the targets list. Any port-specific settings will need to be mapped into `spec.portLevelMtls`. **Authentication** Additional authentication methods specified in `spec.origins`, must be mapped into a `security.istio.io/v1beta1` RequestAuthentication resource. `spec.selector.matchLabels` must be configured similarly to the same field on PeerAuthentication. Configuration specific to JWT principals from `spec.origins.jwt` items map to similar fields in `spec.rules` items. - `spec.origins[x].jwt.triggerRules` specified in the Policy must be mapped into one or more `security.istio.io/v1beta1` AuthorizationPolicy resources. Any `spec.selector.labels` must be configured similarly to the same field on RequestAuthentication. - `spec.origins[x].jwt.triggerRules.excludedPaths` must be mapped into an AuthorizationPolicy whose spec.action is set to ALLOW, with `spec.rules[x].to.operation.path` entries matching the excluded paths. - `spec.origins[x].jwt.triggerRules.includedPaths` must be mapped into a separate AuthorizationPolicy whose `spec.action` is set to `ALLOW`, with `spec.rules[x].to.operation.path` entries matching the included paths, and `spec.rules.[x].from.source.requestPrincipals` entries that align with the `specified spec.origins[x].jwt.issuer` in the Policy resource. **ServiceMeshPolicy (maistra.io/v1)** ServiceMeshPolicy was configured automatically for the Service Mesh control plane through the `spec.istio.global.mtls.enabled` in the v1 resource or `spec.security.dataPlane.mtls` in the v2 resource setting. For v2 control planes, a functionally equivalent PeerAuthentication resource is created during installation. This feature is deprecated in Red Hat OpenShift Service Mesh version 2.0 **RbacConfig, ServiceRole, ServiceRoleBinding (rbac.istio.io/v1alpha1)** These resources were replaced by the `security.istio.io/v1beta1` AuthorizationPolicy resource. Mimicking RbacConfig behavior requires writing a default AuthorizationPolicy whose settings depend on the spec.mode specified in the RbacConfig. - When `spec.mode` is set to `OFF`, no resource is required as the default policy is ALLOW, unless an AuthorizationPolicy applies to the request. - When `spec.mode` is set to ON, set `spec: {}`. You must create AuthorizationPolicy policies for all services in the mesh. - `spec.mode` is set to `ON_WITH_INCLUSION`, must create an AuthorizationPolicy with `spec: {}` in each included namespace. Inclusion of individual services is not supported by AuthorizationPolicy. However, as soon as any AuthorizationPolicy is created that applies to the workloads for the service, all other requests not explicitly allowed will be denied. - When `spec.mode` is set to `ON_WITH_EXCLUSION`, it is not supported by AuthorizationPolicy. A global DENY policy can be created, but an AuthorizationPolicy must be created for every workload in the mesh because there is no allow-all policy that can be applied to either a namespace or a workload. AuthorizationPolicy includes configuration for both the selector to which the configuration applies, which is similar to the function ServiceRoleBinding provides and the rules which should be applied, which is similar to the function ServiceRole provides. **ServiceMeshRbacConfig (maistra.io/v1)** This resource is replaced by using a `security.istio.io/v1beta1` AuthorizationPolicy resource with an empty spec.selector in the Service Mesh control plane’s namespace. This policy will be the default authorization policy applied to all workloads in the mesh. For specific migration details, see RbacConfig above. ##### Mixer plugins {#ossm-migrating-mixer_ossm-upgrade} Mixer components are disabled by default in version 2.0. If you rely on Mixer plugins for your workload, you must configure your version 2.0 `ServiceMeshControlPlane` to include the Mixer components. To enable the Mixer policy components, add the following snippet to your `ServiceMeshControlPlane`. ```yaml spec: policy: type: Mixer ``` To enable the Mixer telemetry components, add the following snippet to your `ServiceMeshControlPlane`. ```yaml spec: telemetry: type: Mixer ``` Legacy mixer plugins can also be migrated to WASM and integrated using the new ServiceMeshExtension (maistra.io/v1alpha1) custom resource. Built-in WASM filters included in the upstream Istio distribution are not available in Red Hat OpenShift Service Mesh 2.0. ##### Mutual TLS changes {#ossm-migrating-mtls_ossm-upgrade} When using mTLS with workload specific PeerAuthentication policies, a corresponding DestinationRule is required to allow traffic if the workload policy differs from the namespace/global policy. Auto mTLS is enabled by default, but can be disabled by setting `spec.security.dataPlane.automtls` to false in the `ServiceMeshControlPlane` resource. When disabling auto mTLS, DestinationRules may be required for proper communication between services. For example, setting PeerAuthentication to `STRICT` for one namespace may prevent services in other namespaces from accessing them, unless a DestinationRule configures TLS mode for the services in the namespace. For information about mTLS, see [Enabling mutual Transport Layer Security (mTLS)](/openshift-docs-markdown/service_mesh/v2x/ossm-security#ossm-security-mtls_ossm-security) ###### Other mTLS Examples {#_other_mtls_examples} To disable mTLS For productpage service in the bookinfo sample application, your Policy resource was configured the following way for Red Hat OpenShift Service Mesh v1.1. ```yaml {title="Example Policy resource"} apiVersion: authentication.istio.io/v1alpha1 kind: Policy metadata: name: productpage-mTLS-disable namespace: spec: targets: - name: productpage ``` To disable mTLS For productpage service in the bookinfo sample application, use the following example to configure your PeerAuthentication resource for Red Hat OpenShift Service Mesh v2.0. ```yaml {title="Example PeerAuthentication resource"} apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: name: productpage-mTLS-disable namespace: spec: mtls: mode: DISABLE selector: matchLabels: # this should match the selector for the "productpage" service app: productpage ``` To enable mTLS With JWT authentication for the `productpage` service in the bookinfo sample application, your Policy resource was configured the following way for Red Hat OpenShift Service Mesh v1.1. ```yaml {title="Example Policy resource"} apiVersion: authentication.istio.io/v1alpha1 kind: Policy metadata: name: productpage-mTLS-with-JWT namespace: spec: targets: - name: productpage ports: - number: 9000 peers: - mtls: origins: - jwt: issuer: "https://securetoken.google.com" audiences: - "productpage" jwksUri: "https://www.googleapis.com/oauth2/v1/certs" jwtHeaders: - "x-goog-iap-jwt-assertion" triggerRules: - excludedPaths: - exact: /health_check principalBinding: USE_ORIGIN ``` To enable mTLS With JWT authentication for the productpage service in the bookinfo sample application, use the following example to configure your PeerAuthentication resource for Red Hat OpenShift Service Mesh v2.0. ```yaml {title="Example PeerAuthentication resource"} #require mtls for productpage:9000 apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: name: productpage-mTLS-with-JWT namespace: spec: selector: matchLabels: # this should match the selector for the "productpage" service app: productpage portLevelMtls: 9000: mode: STRICT --- #JWT authentication for productpage apiVersion: security.istio.io/v1beta1 kind: RequestAuthentication metadata: name: productpage-mTLS-with-JWT namespace: spec: selector: matchLabels: # this should match the selector for the "productpage" service app: productpage jwtRules: - issuer: "https://securetoken.google.com" audiences: - "productpage" jwksUri: "https://www.googleapis.com/oauth2/v1/certs" fromHeaders: - name: "x-goog-iap-jwt-assertion" --- #Require JWT token to access product page service from #any client to all paths except /health_check apiVersion: security.istio.io/v1beta1 kind: AuthorizationPolicy metadata: name: productpage-mTLS-with-JWT namespace: spec: action: ALLOW selector: matchLabels: # this should match the selector for the "productpage" service app: productpage rules: - to: # require JWT token to access all other paths - operation: notPaths: - /health_check from: - source: # if using principalBinding: USE_PEER in the Policy, # then use principals, e.g. # principals: # - “*” requestPrincipals: - “*” - to: # no JWT token required to access health_check - operation: paths: - /health_check ``` #### Configuration recipes {#ossm-migrating-config-recipes_ossm-upgrade} You can configure the following items with these configuration recipes. ##### Mutual TLS in a data plane {#ossm-migrating-config-mtls_ossm-upgrade} Mutual TLS for data plane communication is configured through `spec.security.dataPlane.mtls` in the `ServiceMeshControlPlane` resource, which is `false` by default. ##### Custom signing key {#ossm-migrating-config-sign-key_ossm-upgrade} Istiod manages client certificates and private keys used by service proxies. By default, Istiod uses a self-signed certificate for signing, but you can configure a custom certificate and private key. For more information about how to configure signing keys, see [Adding an external certificate authority key and certificate](/openshift-docs-markdown/service_mesh/v2x/ossm-security#ossm-cert-manage_ossm-security) ##### Tracing {#ossm-migrating-config-tracing_ossm-upgrade} Tracing is configured in `spec.tracing`. Currently, the only type of tracer that is supported is `Jaeger`. Sampling is a scaled integer representing 0.01% increments, for example, 1 is 0.01% and 10000 is 100%. The tracing implementation and sampling rate can be specified: ```yaml spec: tracing: sampling: 100 # 1% type: Jaeger ``` Jaeger is configured in the `addons` section of the `ServiceMeshControlPlane` resource. ```yaml spec: addons: jaeger: name: jaeger install: storage: type: Memory # or Elasticsearch for production mode memory: maxTraces: 100000 elasticsearch: # the following values only apply if storage:type:=Elasticsearch storage: # specific storageclass configuration for the Jaeger Elasticsearch (optional) size: "100G" storageClassName: "storageclass" nodeCount: 3 redundancyPolicy: SingleRedundancy runtime: components: tracing.jaeger: {} # general Jaeger specific runtime configuration (optional) tracing.jaeger.elasticsearch: #runtime configuration for Jaeger Elasticsearch deployment (optional) container: resources: requests: memory: "1Gi" cpu: "500m" limits: memory: "1Gi" ``` The Jaeger installation can be customized with the `install` field. Container configuration, such as resource limits is configured in `spec.runtime.components.jaeger` related fields. If a Jaeger resource matching the value of `spec.addons.jaeger.name` exists, the Service Mesh control plane will be configured to use the existing installation. Use an existing Jaeger resource to fully customize your Jaeger installation. ##### Visualization {#ossm-migrating-config-vis_ossm-upgrade} Kiali and Grafana are configured under the `addons` section of the `ServiceMeshControlPlane` resource. ```yaml spec: addons: grafana: enabled: true install: {} # customize install kiali: enabled: true name: kiali install: {} # customize install ``` The Grafana and Kiali installations can be customized through their respective `install` fields. Container customization, such as resource limits, is configured in `spec.runtime.components.kiali` and `spec.runtime.components.grafana`. If an existing Kiali resource matching the value of name exists, the Service Mesh control plane configures the Kiali resource for use with the control plane. Some fields in the Kiali resource are overridden, such as the `accessible_namespaces` list, as well as the endpoints for Grafana, Prometheus, and tracing. Use an existing resource to fully customize your Kiali installation. ##### Resource utilization and scheduling {#_resource_utilization_and_scheduling} Resources are configured under `spec.runtime.`. The following component names are supported. | Component | Description | Versions supported | | --- | --- | --- | | security | Citadel container | v1.0/1.1 | | galley | Galley container | v1.0/1.1 | | pilot | Pilot/Istiod container | v1.0/1.1/2.0 | | mixer | istio-telemetry and istio-policy containers | v1.0/1.1 | | `mixer.policy` | istio-policy container | v2.0 | | `mixer.telemetry` | istio-telemetry container | v2.0 | | `global.oauthproxy` | oauth-proxy container used with various addons | v1.0/1.1/2.0 | | `sidecarInjectorWebhook` | sidecar injector webhook container | v1.0/1.1 | | `tracing.jaeger` | general Jaeger container - not all settings may be applied. Complete customization of Jaeger installation is supported by specifying an existing Jaeger resource in the Service Mesh control plane configuration. | v1.0/1.1/2.0 | | `tracing.jaeger.agent` | settings specific to Jaeger agent | v1.0/1.1/2.0 | | `tracing.jaeger.allInOne` | settings specific to Jaeger allInOne | v1.0/1.1/2.0 | | `tracing.jaeger.collector` | settings specific to Jaeger collector | v1.0/1.1/2.0 | | `tracing.jaeger.elasticsearch` | settings specific to Jaeger elasticsearch deployment | v1.0/1.1/2.0 | | `tracing.jaeger.query` | settings specific to Jaeger query | v1.0/1.1/2.0 | | prometheus | prometheus container | v1.0/1.1/2.0 | | kiali | Kiali container - complete customization of Kiali installation is supported by specifying an existing Kiali resource in the Service Mesh control plane configuration. | v1.0/1.1/2.0 | | grafana | Grafana container | v1.0/1.1/2.0 | | 3scale | 3scale container | v1.0/1.1/2.0 | | `wasmExtensions.cacher` | WASM extensions cacher container | v2.0 - tech preview | Some components support resource limiting and scheduling. For more information, see [Performance and scalability](/openshift-docs-markdown/service_mesh/v2x/ossm-performance-scalability#ossm-performance-scalability). #### Next steps for migrating your applications and workloads {#ossm-migrrating-apps_ossm-upgrade} Move the application workload to the new mesh and remove the old instances to complete your upgrade. ## Upgrading the data plane {#upgrading-data-plane} 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. ### Updating your applications and workloads {#ossm-upgrading-apps-workloads_ossm-upgrade} 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: ```terminal $ oc rollout restart ``` You must perform a rolling update for all applications that make up the mesh.