From 40c7f736291652f25bba19fe2809904160eb4178 Mon Sep 17 00:00:00 2001 From: Michael Zalimeni Date: Mon, 28 Oct 2024 13:06:28 -0400 Subject: [PATCH] [NET-1151 NET-11046] docs: clarify request normalization and L7 headers feature availability (#21855) docs: clarify request normalization and L7 headers feature availability - Add notes on feature availability tied to specific fix versions - Add missing 1.20 upgrade entry - Remove erroneous 1.17 upgrade entry (version DNE) - Add missing HCL variant for service intentions config --- website/content/docs/connect/config-entries/mesh.mdx | 2 ++ .../docs/connect/config-entries/service-intentions.mdx | 10 +++++++--- website/content/docs/connect/security.mdx | 2 ++ website/content/docs/upgrading/upgrade-specific.mdx | 10 ++++++---- 4 files changed, 17 insertions(+), 7 deletions(-) diff --git a/website/content/docs/connect/config-entries/mesh.mdx b/website/content/docs/connect/config-entries/mesh.mdx index b64062e518..cf75c4bfa4 100644 --- a/website/content/docs/connect/config-entries/mesh.mdx +++ b/website/content/docs/connect/config-entries/mesh.mdx @@ -268,6 +268,8 @@ Note that the Kubernetes example does not include a `partition` field. Configura Enable options under `HTTP.Incoming.RequestNormalization` to apply normalization to all inbound traffic to mesh proxies. +~> **Compatibility warning**: This feature is available as of Consul CE 1.20.1 and Consul Enterprise 1.20.1, 1.19.2, 1.18.3, and 1.15.15. We recommend upgrading to the latest version of Consul to take advantage of the latest features and improvements. + ```hcl diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 4440b2a76c..47d980f9a8 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -48,7 +48,9 @@ The following outline shows how to format the service intentions configuration e - [`Exact`](#sources-permissions-http-header): string - [`Prefix`](#sources-permissions-http-header): string - [`Suffix`](#sources-permissions-http-header): string - - [`Regex`](#sources-permissions-http-header): string + - [`Contains`](#spec-sources-permissions-http-header): string + - [`Regex`](#spec-sources-permissions-http-header): string + - [`IgnoreCase`](#spec-sources-permissions-http-header): boolean | `false` - [`Invert`](#sources-permissions-http-header): boolean | `false` - [`Precedence`](#sources-precedence): number - [`Type`](#sources-type): string | `consul` @@ -648,7 +650,9 @@ Each member of the `Header` list is a map that contains a `Name` field and at le | `Exact` | Specifies a value for the header key set in the `Name` field. If the request header value matches the `Exact` value, Consul applies the permission. Do not specify `Exact` if `Present`, `Prefix`, `Suffix`, or `Regex` are configured in the same `Header` configuration. | string | optional | | `Prefix` | Specifies a prefix value for the header key set in the `Name` field. If the request header value starts with the `Prefix` value, Consul applies the permission. Do not specify `Prefix` if `Present`, `Exact`, `Suffix`, or `Regex` are configured in the same `Header` configuration. | string | optional | | `Suffix` | Specifies a suffix value for the header key set in the `Name` field. If the request header value ends with the `Suffix` value, Consul applies the permission. Do not specify `Suffix` if `Present`, `Exact`, `Prefix`, or `Regex` are configured in the same `Header` configuration. | string | optional | -| `Regex` | Specifies a regular expression pattern as the value for the header key set in the `Name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `Regex` if `Present`, `Exact`, `Prefix`, or `Suffix` are configured in the same `Header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional | +| `Contains` | Specifies a contains value for the header key set in the `Name` field. If the request header value includes the `Contains` value, Consul applies the permission. Do not specify `Contains` if `Present`, `Exact`, `Prefix`, `Suffix`, or `Regex` are configured in the same `header` configuration. | string | optional | +| `Regex` | Specifies a regular expression pattern as the value for the header key set in the `Name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `Regex` if `Present`, `Exact`, `Prefix`, `Suffix`, or `Contains` are configured in the same `Header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional | +| `IgnoreCase` | Ignores the case of the provided header value when matching with `Exact`, `Prefix`, `Suffix`, or `Contains`. Default is `false`. | boolean | optional | | `Invert` | Inverts the matching logic configured in the `Header`. Default is `false`. | boolean | optional | ### `Sources[].Precedence` @@ -964,7 +968,7 @@ Specifies a set of criteria for matching HTTP request headers. The request heade Each member of the `header` list is a map that contains a `name` field and at least one match criterion. -~> **Warning**: If it is possible for a header to contain multiple values, we recommend using `contains` or `regex` rather than `exact`, `prefix`, or `suffix`. Envoy internally concatenates multiple header values into a single CSV value prior to applying match rules, which may result in match rules that depend on the beginning or end of a string vulnerable to circumvention. A more robust alternative is using `contains` or, if a stricter value match is required, configuring a regex pattern that is tolerant of comma-separated values. +~> **Warning**: If it is possible for a header to contain multiple values, we recommend using `contains` or `regex` rather than `exact`, `prefix`, or `suffix`. Envoy internally concatenates multiple header values into a single CSV value prior to applying match rules, which may result in match rules that depend on the beginning or end of a string vulnerable to circumvention. A more robust alternative is using `contains` or, if a stricter value match is required, configuring a regex pattern that is tolerant of comma-separated values. These options are available as of Consul CE 1.20.1 and Consul Enterprise 1.20.1, 1.19.2, 1.18.3, and 1.15.15. The following table describes the parameters that each member of the `header` list may contain: diff --git a/website/content/docs/connect/security.mdx b/website/content/docs/connect/security.mdx index a65d4fabcd..cefcaa3be2 100644 --- a/website/content/docs/connect/security.mdx +++ b/website/content/docs/connect/security.mdx @@ -42,6 +42,8 @@ an explicit intention. ### Request Normalization Configured for L7 Intentions +~> **Compatibility warning**: This feature is available as of Consul CE 1.20.1 and Consul Enterprise 1.20.1, 1.19.2, 1.18.3, and 1.15.15. We recommend upgrading to the latest version of Consul to take advantage of the latest features and improvements. + Atypical traffic patterns may interfere with the enforcement of L7 intentions. For example, if a service makes request to a non-normalized URI path and Consul is not configured to force path normalization, it becomes possible to circumvent path match rules. While a diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index c7fec8cb34..4ff5eb8c30 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -14,6 +14,12 @@ provided for their upgrades as a result of new features or changed behavior. This page is used to document those details separately from the standard upgrade flow. +## Consul 1.20.x + +### Mesh traffic request path normalization enabled by default + +As of Consul v1.20.1, inbound traffic to mesh proxies will have Envoy request [path normalization](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) applied by default. This should not interfere with the majority of service traffic, but can be disabled if needed by setting `http.incoming.request_normalization.insecure_disable_path_normalization` to `true` in the [global `mesh` configuration entry](/consul/docs/connect/config-entries/mesh#request-normalization). This setting is generally safe to change if not using L7 intentions with path matching. + ## Consul v1.19.x ### Health endpoint status filtering is now processed on the server side when using client agents @@ -74,10 +80,6 @@ service-defaults are configured in each partition and namespace before upgrading #### ACL tokens with templated policies [ACL templated policies](/consul/docs/security/acl#templated-policies) were added to 1.17.0 to simplify obtaining the right permissions for ACL tokens. When performing a [rolling upgrade](/consul/tutorials/datacenter-operations/upgrade-federated-environment#server-rolling-upgrade) and a version of Consul prior to 1.17.x is presented with a token created Consul v1.17.x or newer that contains templated policies, the templated policies field is not recognized. As a result, the token might not have the expected permissions on the older version of Consul. -### Mesh traffic request path normalization enabled by default - -As of Consul v1.17.8, inbound traffic to mesh proxies will have Envoy request [path normalization](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) applied by default. This should not interfere with the majority of service traffic, but can be disabled if needed by setting `http.incoming.request_normalization.insecure_disable_path_normalization` to `true` in the [global `mesh` configuration entry](/consul/docs/connect/config-entries/mesh#request-normalization). This setting is generally safe to change if not using L7 intentions with path matching. - ## Consul 1.16.x ### Known issues