Skip to content

Commit

Permalink
Merge 21263c8 into backport/zalimeni/net-4403-prop-override-improve-d…
Browse files Browse the repository at this point in the history 
…ocs-example/moderately-glorious-flounder
  • Loading branch information
@hc-github-team-consul-core
hc-github-team-consul-core authored Jun 20, 2023
2 parents 374a1ca + 21263c8 commit 9eae633
Show file tree
Hide file tree
Showing 4 changed files with 95 additions and 64 deletions.
20 changes: 19 additions & 1 deletion test/integration/connect/envoy/case-property-override/setup.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
5 changes: 3 additions & 2 deletions test/integration/connect/envoy/case-property-override/verify.bats
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" {
Expand Down
79 changes: 43 additions & 36 deletions ...ntent/docs/connect/proxies/envoy-extensions/configuration/property-override.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,14 @@ Patches = [
TrafficDirection = "<inbound or outbound>"
Services = [
{
Name = "<name of service to filter for>",
Name = "<name of service to filter for>"
Namespace = "<Consul namespace containing the service>"
Partition = "<Consul partition containing the service>"
}
]
Op = "<add or remove>",
Path = "<path/to/field>",
}
Op = "<add or remove>"
Path = "</path/to/field>"
Value = "<values or map of field-values>"
}
]
Expand Down Expand Up @@ -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"
Expand All @@ -183,18 +184,18 @@ EnvoyExtensions = [
},
},
"Op" = "add",
"Path" = "/outlier_detection/enforcing_consecutive_5xx",
"Value" = 1234,
"Path" = "/respect_dns_ttl",
"Value" = true,
}
]
}
}
]
```

### 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"
Expand All @@ -208,65 +209,71 @@ 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
}
]
}
}
]
```

### 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"
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.
55 changes: 30 additions & 25 deletions website/content/docs/connect/proxies/envoy-extensions/usage/property-override.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,17 +23,17 @@ 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:

<Tabs>
<Tab heading="HCL" group="hcl">
<CodeBlockConfig filename="property-override-extension-service-defaults.hcl">

```hcl
Kind = "service-defaults"
Name = "global"
Name = "api"
Protocol = "http"
EnvoyExtensions = [
{
Expand All @@ -50,8 +50,8 @@ EnvoyExtensions = [
}]
}
Op = "add"
Path = "/upstream_connection_options/tcp_keepalive/keepalive_probes"
Value = 5
Path = "/respect_dns_ttl"
Value = true
}
]
}
Expand All @@ -66,35 +66,35 @@ EnvoyExtensions = [

```json
"kind": "service-defaults",
"name": "global",
"name": "api",
"protocol": "http",
"envoy_extensions": [{
"envoyExtensions": [{
"name": "builtin/property-override",
"arguments": {
"proxyType": "connect-proxy",
"patches": [{
"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
}]
}
}]
```
</CodeBlockConfig>
</Tab>
<Tab heading="Kubernetes" group="kubernetes">
<CodeBlockConfig filename="property-override-extension-proxy-defaults.yaml">
<CodeBlockConfig filename="property-override-extension-service-defaults.yaml">

```yaml
apiversion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: global
name: api
spec:
protocol: http
envoyExtensions:
Expand All @@ -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
```
</CodeBlockConfig>
Expand All @@ -136,6 +136,7 @@ EnvoyExtensions = [
{
Name = "builtin/property-override"
Arguments = {
Debug = true
ProxyType = "connect-proxy"
Patches = [
{
Expand All @@ -146,7 +147,7 @@ EnvoyExtensions = [
Op = "add"
Path = ""
Value = 5
}
}
]
}
}
Expand All @@ -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
```


Expand Down

0 comments on commit 9eae633

Please sign in to comment.