////
Module included in the following assemblies:
* service_mesh/v1x/servicemesh-release-notes.adoc
////

:_mod-docs-content-type: PROCEDURE
[id="ossm-rn-new-features-1x_{context}"]
= New Features

////
*Feature* – Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes.
*Reason* – If known, include why has the enhancement been implemented (use case, performance, technology, etc.). For example, showcases integration of X with Y, demonstrates Z API feature, includes latest framework bug fixes. There may not have been a 'problem' previously, but system behavior may have changed.
*Result* – If changed, describe the current user experience
////
{SMProductName} provides a number of key capabilities uniformly across a network of services:

* *Traffic Management* - Control the flow of traffic and API calls between services, make calls more reliable, and make the network more robust in the face of adverse conditions.
* *Service Identity and Security* - Provide services in the mesh with a verifiable identity and provide the ability to protect service traffic as it flows over networks of varying degrees of trustworthiness.
* *Policy Enforcement* - Apply organizational policy to the interaction between services, ensure access policies are enforced and resources are fairly distributed among consumers. Policy changes are made by configuring the mesh, not by changing application code.
* *Telemetry* - Gain understanding of the dependencies between services and the nature and flow of traffic between them, providing the ability to quickly identify issues.

== New features {SMProductName} 1.1.18.2

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs).

=== Component versions included in {SMProductName} version 1.1.18.2

|===
|Component |Version

|Istio
|1.4.10

|Jaeger
|1.30.2

|Kiali
|1.12.21.1

|3scale Istio Adapter
|1.0.0
|===

== New features {SMProductName} 1.1.18.1

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs).

=== Component versions included in {SMProductName} version 1.1.18.1

|===
|Component |Version

|Istio
|1.4.10

|Jaeger
|1.30.2

|Kiali
|1.12.20.1

|3scale Istio Adapter
|1.0.0
|===

== New features {SMProductName} 1.1.18

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs).

=== Component versions included in {SMProductName} version 1.1.18

|===
|Component |Version

|Istio
|1.4.10

|Jaeger
|1.24.0

|Kiali
|1.12.18

|3scale Istio Adapter
|1.0.0
|===

== New features {SMProductName} 1.1.17.1

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs).

=== Change in how {SMProductName} handles URI fragments

{SMProductName} contains a remotely exploitable vulnerability, link:https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-39156[CVE-2021-39156], where an HTTP request with a fragment (a section in the end of a URI that begins with a # character) in the URI path could bypass the Istio URI path-based authorization policies. For instance, an Istio authorization policy denies requests sent to the URI path `/user/profile`. In the vulnerable versions, a request with URI path `/user/profile#section1` bypasses the deny policy and routes to the backend (with the normalized URI `path /user/profile%23section1`), possibly leading to a security incident.

You are impacted by this vulnerability if you use authorization policies with DENY actions and `operation.paths`, or ALLOW actions and `operation.notPaths`.

With the mitigation, the fragment part of the request’s URI is removed before the authorization and routing. This prevents a request with a fragment in its URI from bypassing authorization policies which are based on the URI without the fragment part.

=== Required update for authorization policies

Istio generates hostnames for both the hostname itself and all matching ports. For instance, a virtual service or Gateway for a host of "httpbin.foo" generates a config matching "httpbin.foo and httpbin.foo:*". However, exact match authorization policies only match the exact string given for the `hosts` or `notHosts` fields.

Your cluster is impacted if you have `AuthorizationPolicy` resources using exact string comparison for the rule to determine link:https://istio.io/latest/docs/reference/config/security/authorization-policy/#Operation[hosts or notHosts].

You must update your authorization policy link:https://istio.io/latest/docs/reference/config/security/authorization-policy/#Rule[rules] to use prefix match instead of exact match.  For example, replacing `hosts: ["httpbin.com"]` with `hosts: ["httpbin.com:*"]` in the first `AuthorizationPolicy` example.

.First example AuthorizationPolicy using prefix match
[source,yaml]
----
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: httpbin
  namespace: foo
spec:
  action: DENY
  rules:
  - from:
    - source:
        namespaces: ["dev"]
    to:
    - operation:
        hosts: [“httpbin.com”,"httpbin.com:*"]
----

.Second example AuthorizationPolicy using prefix match
[source,yaml]
----
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: httpbin
  namespace: default
spec:
  action: DENY
  rules:
  - to:
    - operation:
        hosts: ["httpbin.example.com:*"]
----

== New features {SMProductName} 1.1.17

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.16

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.15

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.14

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

[IMPORTANT]
====
There are manual steps that must be completed to address CVE-2021-29492 and CVE-2021-31920.
====

[id="manual-updates-cve-2021-29492_{context}"]
=== Manual updates required by CVE-2021-29492 and CVE-2021-31920

Istio contains a remotely exploitable vulnerability where an HTTP request path with multiple slashes or escaped slash characters (`%2F` or `%5C`) could potentially bypass an Istio authorization policy when path-based authorization rules are used.

For example, assume an Istio cluster administrator defines an authorization DENY policy to reject the request at path `/admin`. A request sent to the URL path `//admin` will NOT be rejected by the authorization policy.

According to https://tools.ietf.org/html/rfc3986#section-6[RFC 3986], the path `//admin` with multiple slashes should technically be treated as a different path from the `/admin`. However, some backend services choose to normalize the URL paths by merging multiple slashes into a single slash. This can result in a bypass of the authorization policy (`//admin` does not match `/admin`), and a user can access the resource at path `/admin` in the backend; this would represent a security incident.

Your cluster is impacted by this vulnerability if you have authorization policies using `ALLOW action + notPaths` field or `DENY action + paths field` patterns. These patterns are vulnerable to unexpected policy bypasses.

Your cluster is NOT impacted by this vulnerability if:

* You don’t have authorization policies.
* Your authorization policies don’t define `paths` or `notPaths` fields.
* Your authorization policies use `ALLOW action + paths` field or `DENY action + notPaths` field patterns. These patterns could only cause unexpected rejection instead of policy bypasses. The upgrade is optional for these cases.

[NOTE]
====
The {SMProductName} configuration location for path normalization is different from the Istio configuration.
====

=== Updating the path normalization configuration

Istio authorization policies can be based on the URL paths in the HTTP request.
https://en.wikipedia.org/wiki/URI_normalization[Path normalization], also known as URI normalization, modifies and standardizes the incoming requests' paths so that the normalized paths can be processed in a standard way.
Syntactically different paths may be equivalent after path normalization.

Istio supports the following normalization schemes on the request paths before evaluating against the authorization policies and routing the requests:

.Normalization schemes
[options="header"]
[cols="a, a, a, a"]
|====
| Option | Description | Example |Notes
|`NONE`
|No normalization is done. Anything received by Envoy will be forwarded exactly as-is to any backend service.
|`../%2Fa../b` is evaluated by the authorization policies and sent to your service.
|This setting is vulnerable to CVE-2021-31920.

|`BASE`
|This is currently the option used in the *default* installation of Istio. This applies the https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-normalize-path[`normalize_path`] option on Envoy proxies, which follows https://tools.ietf.org/html/rfc3986[RFC 3986] with extra normalization to convert backslashes to forward slashes.
|`/a/../b` is normalized to `/b`. `\da` is normalized to `/da`.
|This setting is vulnerable to CVE-2021-31920.

| `MERGE_SLASHES`
| Slashes are merged after the _BASE_ normalization.
| `/a//b` is normalized to `/a/b`.
|Update to this setting to mitigate CVE-2021-31920.

|`DECODE_AND_MERGE_SLASHES`
|The strictest setting when you allow all traffic by default. This setting is recommended, with the caveat that you must thoroughly test your authorization policies routes. https://tools.ietf.org/html/rfc3986#section-2.1[Percent-encoded] slash and backslash characters (`%2F`, `%2f`, `%5C` and `%5c`) are decoded to `/` or `\`, before the `MERGE_SLASHES` normalization.
|`/a%2fb` is normalized to `/a/b`.
|Update to this setting to mitigate CVE-2021-31920.  This setting is more secure, but also has the potential to break applications.  Test your applications before deploying to production.
|====

The normalization algorithms are conducted in the following order:

. Percent-decode `%2F`, `%2f`, `%5C` and `%5c`.
. The https://tools.ietf.org/html/rfc3986[RFC 3986] and other normalization implemented by the https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-normalize-path[`normalize_path`] option in Envoy.
. Merge slashes.

[WARNING]
====
While these normalization options represent recommendations from HTTP standards and common industry practices, applications may interpret a URL in any way it chooses to. When using denial policies, ensure that you understand how your application behaves.
====

=== Path normalization configuration examples

Ensuring Envoy normalizes request paths to match your backend services' expectations is critical to the security of your system.
The following examples can be used as a reference for you to configure your system.
The normalized URL paths, or the original URL paths if `NONE` is selected, will be:

. Used to check against the authorization policies.
. Forwarded to the backend application.

.Configuration examples
[options="header"]
[cols="a, a"]
|====
|If your application... |Choose...
|Relies on the proxy to do normalization
|`BASE`, `MERGE_SLASHES` or `DECODE_AND_MERGE_SLASHES`

|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986] and does not merge slashes.
|`BASE`

|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986] and merges slashes, but does not decode https://tools.ietf.org/html/rfc3986#section-2.1[percent-encoded] slashes.
|`MERGE_SLASHES`

|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986], decodes https://tools.ietf.org/html/rfc3986#section-2.1[percent-encoded] slashes, and merges slashes.
|`DECODE_AND_MERGE_SLASHES`

|Processes request paths in a way that is incompatible with https://tools.ietf.org/html/rfc3986[RFC 3986].
|`NONE`
|====

=== Configuring your SMCP for path normalization

To configure path normalization for {SMProductName}, specify the following in your `ServiceMeshControlPlane`.  Use the configuration examples to help determine the settings for your system.

.SMCP v1 pathNormalization
[source,yaml]
----
spec:
  global:
    pathNormalization: <option>
----


== New features {SMProductName} 1.1.13

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.12

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.11

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.10

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.9

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.8

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.7

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.6

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.5

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

This release also added support for configuring cipher suites.

== New features {SMProductName} 1.1.4

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

[NOTE]
====
There are manual steps that must be completed to address CVE-2020-8663.
====

[id="manual-updates-cve-2020-8663_{context}"]
=== Manual updates required by CVE-2020-8663

The fix for link:https://bugzilla.redhat.com/show_bug.cgi?id=1844254[CVE-2020-8663]`: envoy: Resource exhaustion when accepting too many connections` added a configurable limit on downstream connections. The configuration option for this limit must be configured to mitigate this vulnerability.

[IMPORTANT]
====
These manual steps are required to mitigate this CVE whether you are using the 1.1 version or the 1.0 version of {SMProductName}.
====

This new configuration option is called `overload.global_downstream_max_connections`, and it is configurable as a proxy `runtime` setting.  Perform the following steps to configure limits at the Ingress Gateway.

.Procedure

. Create a file named `bootstrap-override.json` with the following text to force the proxy to override the bootstrap template and load runtime configuration from disk:
+
  {
    "runtime": {
      "symlink_root": "/var/lib/istio/envoy/runtime"
    }
  }
+
. Create a secret from the `bootstrap-override.json` file, replacing <SMCPnamespace> with the namespace where you created the service mesh control plane (SMCP):
+
[source,terminal]
----
$  oc create secret generic -n <SMCPnamespace> gateway-bootstrap --from-file=bootstrap-override.json
----
+
. Update the SMCP configuration to activate the override.

+
.Updated SMCP configuration example #1
[source,yaml]
----
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
spec:
  istio:
    gateways:
      istio-ingressgateway:
        env:
          ISTIO_BOOTSTRAP_OVERRIDE: /var/lib/istio/envoy/custom-bootstrap/bootstrap-override.json
        secretVolumes:
        - mountPath: /var/lib/istio/envoy/custom-bootstrap
          name: custom-bootstrap
          secretName: gateway-bootstrap
----
+

. To set the new configuration option, create a secret that has the desired value for the `overload.global_downstream_max_connections` setting.  The following example uses a value of `10000`:
+
[source,terminal]
----
$  oc create secret generic -n <SMCPnamespace> gateway-settings --from-literal=overload.global_downstream_max_connections=10000
----
+

. Update the SMCP again to mount the secret in the location where Envoy is looking for runtime configuration:

.Updated SMCP configuration example #2
[source,yaml]
----
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
spec:
  template: default
#Change the version to "v1.0" if you are on the 1.0 stream.
  version: v1.1
  istio:
    gateways:
      istio-ingressgateway:
        env:
          ISTIO_BOOTSTRAP_OVERRIDE: /var/lib/istio/envoy/custom-bootstrap/bootstrap-override.json
        secretVolumes:
        - mountPath: /var/lib/istio/envoy/custom-bootstrap
          name: custom-bootstrap
          secretName: gateway-bootstrap
        # below is the new secret mount
        - mountPath: /var/lib/istio/envoy/runtime
          name: gateway-settings
          secretName: gateway-settings

----

[id="upgrading_es5_es6_{context}"]
=== Upgrading from Elasticsearch 5 to Elasticsearch 6

When updating from Elasticsearch 5 to Elasticsearch 6, you must delete your Jaeger instance, then recreate the Jaeger instance because of an issue with certificates. Re-creating the Jaeger instance triggers creating a new set of certificates.   If you are using persistent storage the same volumes can be mounted for the new Jaeger instance as long as the Jaeger name and namespace for the new Jaeger instance are the same as the deleted Jaeger instance.

.Procedure if Jaeger is installed as part of Red Hat Service Mesh

. Determine the name of your Jaeger custom resource file:
+
[source,terminal]
----
$ oc get jaeger -n istio-system
----
+
You should see something like the following:
+
[source,terminal]
----
NAME     AGE
jaeger   3d21h
----
+
. Copy the generated custom resource file into a temporary directory:
+
[source,terminal]
----
$ oc get jaeger jaeger -oyaml -n istio-system > /tmp/jaeger-cr.yaml
----
+
. Delete the Jaeger instance:
+
[source,terminal]
----
$ oc delete jaeger jaeger -n istio-system
----
+
. Recreate the Jaeger instance from your copy of the custom resource file:
+
[source,terminal]
----
$ oc create -f /tmp/jaeger-cr.yaml -n istio-system
----
+
. Delete the copy of the generated custom resource file:
+
[source,terminal]
----
$ rm /tmp/jaeger-cr.yaml
----


.Procedure if Jaeger not installed as part of Red Hat Service Mesh

Before you begin, create a copy of your Jaeger custom resource file.

. Delete the Jaeger instance by deleting the custom resource file:
+
[source,terminal]
----
$ oc delete -f <jaeger-cr-file>
----
+
For example:
+
[source,terminal]
----
$ oc delete -f jaeger-prod-elasticsearch.yaml
----
+
. Recreate your Jaeger instance from the backup copy of your custom resource file:
+
[source,terminal]
----
$ oc create -f <jaeger-cr-file>
----
+
. Validate that your Pods have restarted:
+
[source,terminal]
----
$ oc get pods -n jaeger-system -w
----
+




== New features {SMProductName} 1.1.3

This release of {SMProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

== New features {SMProductName} 1.1.2

This release of {SMProductName} addresses a security vulnerability.

== New features {SMProductName} 1.1.1

This release of {SMProductName} adds support for a disconnected installation.

== New features {SMProductName} 1.1.0

This release of {SMProductName} adds support for Istio 1.4.6 and Jaeger 1.17.1.

[id="ossm-manual-updates-1.0-1.1_{context}"]
=== Manual updates from 1.0 to 1.1

If you are updating from {SMProductName} 1.0 to 1.1, you must update the `ServiceMeshControlPlane` resource to update the control plane components to the new version.

. In the web console, click the {SMProductName} Operator.

. Click the *Project* menu and choose the project where your `ServiceMeshControlPlane` is deployed from the list, for example `istio-system`.

. Click the name of your control plane, for example `basic-install`.

. Click YAML and add a version field to the `spec:` of your `ServiceMeshControlPlane` resource. For example, to update to {SMProductName} 1.1.0, add `version: v1.1`.

----
spec:
  version: v1.1
  ...
----

The version field specifies the version of {SMProductShortName} to install and defaults to the latest available version.

[NOTE]
====
Note that support for {SMProductName} v1.0 ended in October, 2020.  You must upgrade to either v1.1 or v2.0.
====
