From b7524f72a4782bb457677ecc9b1ccf5544a79f01 Mon Sep 17 00:00:00 2001 From: Michael Zalimeni Date: Wed, 21 Jun 2023 13:17:26 -0400 Subject: [PATCH] Manual backports of Prop Override doc updates (#17830) backport of commit 910a115cd3812cd66fab1cdfc47baeec65415d14 (#17813) backport of commit 21263c8a004dffe7e8fcefc234d80abfa3ec66d5 (#17811) --- .../envoy/case-property-override/setup.sh | 20 ++++- .../envoy/case-property-override/verify.bats | 5 +- .../configuration/property-override.mdx | 86 ++++++++++--------- .../usage/property-override.mdx | 62 +++++++------ 4 files changed, 106 insertions(+), 67 deletions(-) diff --git a/test/integration/connect/envoy/case-property-override/setup.sh b/test/integration/connect/envoy/case-property-override/setup.sh index 1bf2021c0c9a..744055f94966 100644 --- a/test/integration/connect/envoy/case-property-override/setup.sh +++ b/test/integration/connect/envoy/case-property-override/setup.sh @@ -53,12 +53,30 @@ EnvoyExtensions = [ Path = "/upstream_connection_options/tcp_keepalive/keepalive_probes" Value = 1234 }, + { + ResourceFilter = { + ResourceType = "cluster" + TrafficDirection = "outbound" + } + Op = "add" + Path = "/outlier_detection/max_ejection_time/seconds" + Value = 120 + }, + { + ResourceFilter = { + ResourceType = "cluster" + TrafficDirection = "outbound" + } + Op = "add" + Path = "/outlier_detection/max_ejection_time_jitter/seconds" + Value = 1 + }, { ResourceFilter = { ResourceType = "cluster" TrafficDirection = "outbound" Services = [{ - Name = "s2" + Name = "s3" }] } Op = "remove" diff --git a/test/integration/connect/envoy/case-property-override/verify.bats b/test/integration/connect/envoy/case-property-override/verify.bats index 4453409eede5..446ef061da41 100644 --- a/test/integration/connect/envoy/case-property-override/verify.bats +++ b/test/integration/connect/envoy/case-property-override/verify.bats @@ -19,13 +19,14 @@ load helpers [ "$status" == 0 ] [ "$(echo "$output" | jq -r '.upstream_connection_options.tcp_keepalive.keepalive_probes')" == "1234" ] - [ "$(echo "$output" | jq -r '.outlier_detection')" == "null" ] + [ "$(echo "$output" | jq -r '.outlier_detection.max_ejection_time')" == "120s" ] + [ "$(echo "$output" | jq -r '.outlier_detection.max_ejection_time_jitter')" == "1s" ] run get_envoy_cluster_config localhost:19000 s3 [ "$status" == 0 ] [ "$(echo "$output" | jq -r '.upstream_connection_options.tcp_keepalive.keepalive_probes')" == "1234" ] - [ "$(echo "$output" | jq -r '.outlier_detection')" == "{}" ] + [ "$(echo "$output" | jq -r '.outlier_detection')" == "null" ] } @test "s2 proxy is configured with the expected envoy patches" { diff --git a/website/content/docs/connect/proxies/envoy-extensions/configuration/property-override.mdx b/website/content/docs/connect/proxies/envoy-extensions/configuration/property-override.mdx index f88cd476a0bd..8ccb49a391fb 100644 --- a/website/content/docs/connect/proxies/envoy-extensions/configuration/property-override.mdx +++ b/website/content/docs/connect/proxies/envoy-extensions/configuration/property-override.mdx @@ -46,13 +46,14 @@ Patches = [ TrafficDirection = "" Services = [ { - Name = "", + Name = "" Namespace = "" Partition = "" } ] - Op = "", - Path = "", + } + Op = "" + Path = "" Value = "" } ] @@ -117,7 +118,7 @@ The following table describes how to configure a `ResourceFilter`: Specifies the JSON Patch operation to perform when the `ResourceFilter` matches a local Envoy proxy configuration. You can specify one of the following values for each patch: -- `add`: Replaces a property or message specified by [`Path`](#patches-path) with the given value. The JSON patch format does not merge objects. To emulate merges, you must configure discrete `add` operations for each changed field. Consul returns an error if the target field does not exist in the corresponding schema. +- `add`: Replaces a property or message specified by [`Path`](#patches-path) with the given value. The JSON Patch `add` operation does not merge objects. To emulate merges, you must configure discrete `add` operations for each changed field. Consul returns an error if the target field does not exist in the corresponding schema. - `remove`: Unsets the value of the field specified by [`Path`](#patches-path). If the field is not set, no changes are made. Consul returns an error if the target field does not exist in the corresponding schema. #### Values @@ -134,7 +135,7 @@ Specifies where the extension performs the associated operation on the specified The `Path` field does not support addressing array elements or protobuf map field entries. Refer to [Constructing paths](/consul/docs/connect/proxies/envoy-extensions/usage/property-override#constructing-paths) for information about how to construct paths. -When setting fields, the extension sets any unset intermediate fields to their default values. A a single operation on a nested field can set multiple intermediate fields. Because Consul sets the intermediate fields to their default values, you may need to configure subsequent patches to satisfy Envoy or Consul validation. +When setting fields, the extension sets any unset intermediate fields to their default values. A single operation on a nested field can set multiple intermediate fields. Because Consul sets the intermediate fields to their default values, you may need to configure subsequent patches to satisfy Envoy or Consul validation. #### Values @@ -144,9 +145,10 @@ When setting fields, the extension sets any unset intermediate fields to their d ### `Patches[].Value{}` -Defines a value to set at the specified [path](#patches-path) if the [operation](#patches-op) is set to `add`. You can specify either a scalar or enum value or define a map that contains string keys and values corresponding to scalar or enum child fields. Refer to the [example configurations](#examples) for additional guidance and to the [Envoy API documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api) for additional information about Envoy proxy interfaces. +Defines a value to set at the specified [path](#patches-path) if the [operation](#patches-op) is set to `add`. You can specify either a scalar or enum value, an array of scalar or enum values (for repeated fields), or define a map that contains string keys and values corresponding to scalar or enum child fields. Single and repeated scalar and enum values are supported. Refer to the [example configurations](#examples) for additional guidance and to the [Envoy API documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api) for additional information about Envoy proxy interfaces. If Envoy specifies a wrapper as the target field type, the extension automatically coerces simple values to the wrapped type when patching. For example, the value `32768` is allowed when targeting a cluster's `per_connection_buffer_limit_bytes`, which is a `UInt32Value` field. Refer to the [protobuf documentation](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/wrappers.proto) for additional information about wrappers. + #### Values - Default: None @@ -160,9 +162,9 @@ If Envoy specifies a wrapper as the target field type, the extension automatical The following examples demonstrate patterns that you may be able to model your configurations on. -### Enable `enforcing_consecutive_5xx` outlier detection +### Enable `respect_dns_ttl` in a cluster -In the following example, the `add` operation patches an outlier detection property into outbound cluster traffic. The `Path` specifies the `enforcing_consecutive_5xx` interface and sets a value of `1234`: +In the following example, the `add` operation patches the outbound cluster corresponding to the `other-svc` upstream service to enable `respect_dns_ttl`. The `Path` specifies the [Cluster `/respect_dns_ttl`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-field-config-cluster-v3-cluster-respect-dns-ttl) top-level field and `Value` specifies a value of `true`: ```hcl Kind = "service-defaults" @@ -183,8 +185,8 @@ EnvoyExtensions = [ }, }, "Op" = "add", - "Path" = "/outlier_detection/enforcing_consecutive_5xx", - "Value" = 1234, + "Path" = "/respect_dns_ttl", + "Value" = true, } ] } @@ -192,9 +194,9 @@ EnvoyExtensions = [ ] ``` -### Update multiple values in the default map +### Update multiple values in a message field -In the following example, two `ResourceFilter` blocks target outbound traffic to the `db` service and add `/outlier_detection/enforcing_consecutive_5xx` and `/outlier_detection/failure_percentage_request_volume` properties: +In the following example, both `ResourceFilter` blocks target the cluster corresponding to the `other-svc` upstream service and modify [Cluster `/outlier_detection`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/outlier_detection.proto) properties: ```hcl Kind = "service-defaults" @@ -208,27 +210,27 @@ EnvoyExtensions = [ Patches = [ { ResourceFilter = { - ResourceType = "cluster", - TrafficDirection = "outbound", + ResourceType = "cluster" + TrafficDirection = "outbound" Services = [{ Name = "other-svc" - }], - }, - Op = "add", - Path = "/outlier_detection/enforcing_consecutive_5xx", - Value = 1234, + }] + } + Op = "add" + Path = "/outlier_detection/max_ejection_time/seconds" + Value = 120 }, { ResourceFilter = { - ResourceType = "cluster", - TrafficDirection = "outbound", + ResourceType = "cluster" + TrafficDirection = "outbound" Services = [{ Name = "other-svc" - }], - }, - Op = "add", - Path = "/outlier_detection/failure_percentage_request_volume", - Value = 2345, + }] + } + Op = "add" + Path = "/outlier_detection/max_ejection_time_jitter/seconds" + Value = 1 } ] } @@ -236,9 +238,13 @@ EnvoyExtensions = [ ] ``` -### Set multiple values that replace the map +The use of `/seconds` in these examples corresponds to the same field in the [google.protobuf.Duration](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/duration.proto) proto definition, since the extension does not support JSON serialized string forms of common protobuf types (e.g. `120s`). + +-> **Note:** Using separate patches per field preserves any existing configuration of other fields in `outlier_detection` that may be directly set by Consul, such as [`enforcing_consecutive_5xx`](https://developer.hashicorp.com/consul/docs/connect/proxies/envoy#enforcing_consecutive_5xx). + +### Replace a message field -In the following example, a `ResourceFilter` targets outbound traffic to the `db` service and replaces the map of properties located at `/outlier_detection` with `enforcing_consecutive_5xx` and `failure_percentage_request_volume` and properties: +In the following example, a `ResourceFilter` targets the cluster corresponding to the `other-svc` upstream service and _replaces_ the entire map of properties located at `/outlier_detection`, including explicitly set `enforcing_success_rate` and `success_rate_minimum_hosts` properties: ```hcl Kind = "service-defaults" @@ -246,27 +252,29 @@ Name = "my-svc" Protocol = "http" EnvoyExtensions = [ { - Name = "builtin/property-override", + Name = "builtin/property-override" Arguments = { - ProxyType = "connect-proxy", + ProxyType = "connect-proxy" Patches = [ { ResourceFilter = { - ResourceType = "cluster", - TrafficDirection = "outbound", + ResourceType = "cluster" + TrafficDirection = "outbound" Services = [{ Name = "other-svc" - }], - }, - Op = "add", - Path = "/outlier_detection", + }] + } + Op = "add" + Path = "/outlier_detection" Value = { - "enforcing_consecutive_5xx" = 1234, - "failure_percentage_request_volume" = 2345, - }, + "enforcing_success_rate" = 80 + "success_rate_minimum_hosts" = 2 + } } ] } } ] ``` + +Unlike the previous example, other `/outlier_detection` values set by Consul will _not_ be retained unless they match Envoy's defaults, because the entire value of `/outlier_detection` will be replaced. diff --git a/website/content/docs/connect/proxies/envoy-extensions/usage/property-override.mdx b/website/content/docs/connect/proxies/envoy-extensions/usage/property-override.mdx index 805540265787..84cf621930b0 100644 --- a/website/content/docs/connect/proxies/envoy-extensions/usage/property-override.mdx +++ b/website/content/docs/connect/proxies/envoy-extensions/usage/property-override.mdx @@ -8,6 +8,13 @@ description: Learn how to use the property-override extension for Envoy proxies This topic describes how to use the `property-override` extension to set and remove individual properties for the Envoy resources Consul generates. The extension uses the [protoreflect](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect), which enables Consul to dynamically manipulate messages. +The extension currently supports setting scalar and enum fields, removing individual fields addressable by `Path`, and initializing unset intermediate message fields indicated in `Path`. + +It currently does _not_ support the following use cases: +- Adding, updating, or removing repeated field members +- Adding or updating [protobuf `map`](https://protobuf.dev/programming-guides/proto3/#maps) fields +- Adding or updating [protobuf `Any`](https://protobuf.dev/programming-guides/proto3/#any) fields + ## Workflow - Complete the following steps to use the `property-override` extension: @@ -23,9 +30,9 @@ Add Envoy extension configurations to a proxy defaults or service defaults confi - When you configure Envoy extensions on proxy defaults, they apply to every service. - When you configure Envoy extensions on service defaults, they apply to a specific service. -Consul applies Envoy extensions configured in proxy defaults before it applies extensions in service defaults. As a result, the Envoy extension configuration in service defaults may override configurations in proxy defaults. +Consul applies Envoy extensions configured in proxy defaults before it applies extensions in service defaults. As a result, the Envoy extension configuration in service defaults may override configurations in proxy defaults. -In the following service defaults configuration entry example, Consul adds a new `/upstream_connection_options/tcp_keepalive/keepalive_probes-5` field to each of the proxy's cluster configuration for the outbound `db`service upstream. The configuration applies to all `connect-proxy` proxies with services configured to communicate over HTTP: +In the following proxy defaults configuration entry example, Consul sets the `/respect_dns_ttl` field on the `api` service proxy's cluster configuration for the `other-svc` upstream service: @@ -33,7 +40,7 @@ In the following service defaults configuration entry example, Consul adds a new ```hcl Kind = "service-defaults" -Name = "global" +Name = "api" Protocol = "http" EnvoyExtensions = [ { @@ -50,8 +57,8 @@ EnvoyExtensions = [ }] } Op = "add" - Path = "/upstream_connection_options/tcp_keepalive/keepalive_probes" - Value = 5 + Path = "/respect_dns_ttl" + Value = true } ] } @@ -66,9 +73,9 @@ EnvoyExtensions = [ ```json "kind": "service-defaults", -"name": "global", +"name": "api", "protocol": "http", -"envoy_extensions": [{ +"envoyExtensions": [{ "name": "builtin/property-override", "arguments": { "proxyType": "connect-proxy", @@ -76,11 +83,11 @@ EnvoyExtensions = [ "resourceFilter": { "resourceType": "cluster", "trafficDirection": "outbound", - "services": [{ "name": "other-svc" }], - "op": "add", - "path": "/upstream_connection_options/tcp_keepalive/keepalive_probes", - "value": 5 - } + "services": [{ "name": "other-svc" }] + }, + "op": "add", + "path": "/respect_dns_ttl", + "value": true }] } }] @@ -88,13 +95,13 @@ EnvoyExtensions = [ - + ```yaml apiversion: consul.hashicorp.com/v1alpha1 kind: ServiceDefaults metadata: - name: global + name: api spec: protocol: http envoyExtensions: @@ -108,8 +115,8 @@ spec: services: - name: "other-svc" op: "add" - path: "/upstream_connection_options/tcp_keepalive/keepalive_probes", - value: 5 + path: "/respect_dns_ttl", + value: true ``` @@ -136,6 +143,7 @@ EnvoyExtensions = [ { Name = "builtin/property-override" Arguments = { + Debug = true ProxyType = "connect-proxy" Patches = [ { @@ -146,7 +154,7 @@ EnvoyExtensions = [ Op = "add" Path = "" Value = 5 - } + } ] } } @@ -157,19 +165,23 @@ After applying the configuration entry, Consul prints a message that includes th ```shell-session $ consul config write api.hcl -non-empty, non-root Path is required. available cluster fields: -/outlier_detection -/outlier_detection/enforcing_consecutive_5xx -/outlier_detection/failure_percentage_request_volume -/round_robin_lb_config -/round_robin_lb_config/slow_start_config +non-empty, non-root Path is required; +available envoy.config.cluster.v3.Cluster fields: +transport_socket_matches +name +alt_stat_name +type +cluster_type +eds_cluster_config +connect_timeout +... ``` You can use the output to help you construct the appropriate value for the `Path` field. For example: ```shell-session -$ consul config write api.hcl | grep round_robin -/round_robin_lb_config +$ consul config write api.hcl 2>&1 | grep round_robin +round_robin_lb_config ```