diff --git a/test/integration/connect/envoy/case-property-override/setup.sh b/test/integration/connect/envoy/case-property-override/setup.sh index 1bf2021c0..744055f94 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 4453409ee..446ef061d 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 f88cd476a..28e54f27e 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 = "" } ] @@ -160,9 +161,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 +184,8 @@ EnvoyExtensions = [ }, }, "Op" = "add", - "Path" = "/outlier_detection/enforcing_consecutive_5xx", - "Value" = 1234, + "Path" = "/respect_dns_ttl", + "Value" = true, } ] } @@ -192,9 +193,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 +209,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 +237,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`). -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: +-> **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 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 +251,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 805540265..fbe0c357a 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 @@ -23,9 +23,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 +33,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 +50,8 @@ EnvoyExtensions = [ }] } Op = "add" - Path = "/upstream_connection_options/tcp_keepalive/keepalive_probes" - Value = 5 + Path = "/respect_dns_ttl" + Value = true } ] } @@ -66,9 +66,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 +76,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 +88,13 @@ EnvoyExtensions = [ - + ```yaml apiversion: consul.hashicorp.com/v1alpha1 kind: ServiceDefaults metadata: - name: global + name: api spec: protocol: http envoyExtensions: @@ -108,8 +108,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 +136,7 @@ EnvoyExtensions = [ { Name = "builtin/property-override" Arguments = { + Debug = true ProxyType = "connect-proxy" Patches = [ { @@ -146,7 +147,7 @@ EnvoyExtensions = [ Op = "add" Path = "" Value = 5 - } + } ] } } @@ -157,19 +158,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 ```