Skip to content

Commit

Permalink
[NET-1151 NET-11046] docs: clarify request normalization and L7 heade…
Browse files Browse the repository at this point in the history 
…rs 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
  • Loading branch information
@zalimeni @missylbytes
zalimeni authored and missylbytes committed Oct 30, 2024
1 parent e7d1d21 commit 00c0044
Show file tree
Hide file tree
Showing 4 changed files with 17 additions and 7 deletions.
2 changes: 2 additions & 0 deletions website/content/docs/connect/config-entries/mesh.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>

```hcl
Expand Down
10 changes: 7 additions & 3 deletions website/content/docs/connect/config-entries/service-intentions.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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:

Expand Down
2 changes: 2 additions & 0 deletions website/content/docs/connect/security.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 6 additions & 4 deletions website/content/docs/upgrading/upgrade-specific.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 00c0044

Please sign in to comment.