mirror of https://github.com/status-im/consul.git
220 lines
7.6 KiB
Plaintext
220 lines
7.6 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Configure Envoy proxy properties
|
|
description: Learn how to use the property-override extension for Envoy proxies to set and remove individual properties for the Envoy resources Consul generates.
|
|
---
|
|
|
|
# Configure Envoy proxy properties
|
|
|
|
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:
|
|
- Configure an `EnvoyExtensions` block in a service defaults or proxy defaults configuration entry.
|
|
- Apply the configuration entry.
|
|
|
|
!> **Security warning**: The property override extension is an advanced feature capable of introducing unintended consequences or reducing cluster security if used incorrectly. Consul does not enforce TLS retention, intentions, or other security-critical components of the Envoy configuration. Additionally, Consul does not verify that the configuration does not contain errors that affect service traffic.
|
|
|
|
## Add the `EnvoyExtensions`
|
|
|
|
Add Envoy extension configurations to a proxy defaults or service defaults configuration entry. Place the extension configuration in an `EnvoyExtensions` block in the configuration entry.
|
|
|
|
- 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.
|
|
|
|
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 = "api"
|
|
Protocol = "http"
|
|
EnvoyExtensions = [
|
|
{
|
|
Name = "builtin/property-override"
|
|
Arguments = {
|
|
ProxyType = "connect-proxy"
|
|
Patches = [
|
|
{
|
|
ResourceFilter = {
|
|
ResourceType = "cluster"
|
|
TrafficDirection = "outbound"
|
|
Services = [{
|
|
Name = "other-svc"
|
|
}]
|
|
}
|
|
Op = "add"
|
|
Path = "/respect_dns_ttl"
|
|
Value = true
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
```
|
|
</CodeBlockConfig>
|
|
</Tab>
|
|
|
|
<Tab heading="JSON" group="json">
|
|
<CodeBlockConfig filename="property-override-extension-service-defaults.json">
|
|
|
|
```json
|
|
{
|
|
"kind": "service-defaults",
|
|
"name": "api",
|
|
"protocol": "http",
|
|
"envoyExtensions": [{
|
|
"name": "builtin/property-override",
|
|
"arguments": {
|
|
"proxyType": "connect-proxy",
|
|
"patches": [{
|
|
"resourceFilter": {
|
|
"resourceType": "cluster",
|
|
"trafficDirection": "outbound",
|
|
"services": [{ "name": "other-svc" }]
|
|
},
|
|
"op": "add",
|
|
"path": "/respect_dns_ttl",
|
|
"value": true
|
|
}]
|
|
}
|
|
}]
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
</Tab>
|
|
<Tab heading="Kubernetes" group="kubernetes">
|
|
<CodeBlockConfig filename="property-override-extension-service-defaults.yaml">
|
|
|
|
```yaml
|
|
apiversion: consul.hashicorp.com/v1alpha1
|
|
kind: ServiceDefaults
|
|
metadata:
|
|
name: api
|
|
spec:
|
|
protocol: http
|
|
envoyExtensions:
|
|
name = "builtin/property-override"
|
|
arguments:
|
|
proxyType: "connect-proxy",
|
|
patches:
|
|
- resourceFilter:
|
|
resourceType: "cluster"
|
|
trafficDirection: "outbound"
|
|
services:
|
|
- name: "other-svc"
|
|
op: "add"
|
|
path: "/respect_dns_ttl",
|
|
value: true
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
Refer to the [property override configuration reference](/consul/docs/connect/proxies/envoy-extensions/configuration/property-override) for details on how to configure the extension.
|
|
|
|
Refer to the [proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) and [service defaults configuration entry reference](/consul/docs/connect/config-entries/service-defaults) for details on how to define the configuration entries.
|
|
|
|
!> **Warning:** Adding Envoy extensions default proxy configurations may have unintended consequences. We recommend configuring `EnvoyExtensions` in service defaults configuration entries in most cases.
|
|
|
|
### Constructing paths
|
|
|
|
To target the properties for an Envoy resource type, you must specify the path where the properties exist in the [`Path` field](/consul/docs/connect/proxies/envoy-extensions/configuration/property-override#patches-path) of the property override extension configuration. Set the `Path` field to an empty or partially invalid string when saving the configuration entry and Consul returns an error with a list of supported fields for the first unrecognized segment of the path. By default, Consul only returns the first ten fields, but you can set the [`Debug` field](/consul/docs/connect/proxies/envoy-extensions/configuration/property-override#debug) to `true` to direct Consul to output all possible fields.
|
|
|
|
In the following example, Consul outputs the top-level fields available for the Envoy cluster resource:
|
|
|
|
```hcl
|
|
Kind = "service-defaults"
|
|
Name = "api"
|
|
EnvoyExtensions = [
|
|
{
|
|
Name = "builtin/property-override"
|
|
Arguments = {
|
|
Debug = true
|
|
ProxyType = "connect-proxy"
|
|
Patches = [
|
|
{
|
|
ResourceFilter = {
|
|
ResourceType = "cluster"
|
|
TrafficDirection = "outbound"
|
|
}
|
|
Op = "add"
|
|
Path = ""
|
|
Value = 5
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
After applying the configuration entry, Consul prints a message that includes the possible fields for the resource:
|
|
|
|
```shell-session
|
|
$ consul config write api.hcl
|
|
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 2>&1 | grep round_robin
|
|
round_robin_lb_config
|
|
```
|
|
|
|
|
|
|
|
|
|
## Apply the configuration entry
|
|
|
|
If your network is deployed to virtual machines, use the `consul config write` command and specify the proxy defaults or service defaults configuration entry to apply the configuration. For Kubernetes-orchestrated networks, use the `kubectl apply` command. The following example applies the extension in a proxy defaults configuration entry.
|
|
|
|
<Tabs>
|
|
<Tab heading="HCL" group="hcl">
|
|
|
|
```shell-session
|
|
$ consul config write property-override-extension-service-defaults.hcl
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON" group="json">
|
|
|
|
```shell-session
|
|
$ consul config write property-override-extension-service-defaults.json
|
|
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="Kubernetes" group="kubernetes">
|
|
|
|
```shell-session
|
|
$ kubectl apply property-override-extension-service-defaults.yaml
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|