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, 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
fields - Adding or updating protobuf
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:
Refer to the property override configuration reference for details on how to configure the extension.
Refer to the proxy defaults configuration entry reference and service defaults configuration entry reference 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 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 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:
After applying the configuration entry, Consul prints a message that includes the possible fields for the resource:
You can use the output to help you construct the appropriate value for the Path
field. For example:
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.