Property override configuration reference
This topic describes how to configure the property-override
extension so that you can set and remove individual properties on the Envoy resources Consul generates. Refer to Configure Envoy proxy properties for usage information.
Configuration model
The following list outlines the field hierarchy, data types, and requirements for the property-override
configuration. Place the configuration inside the EnvoyExtension.Arguments
field in the proxy defaults or service defaults configuration entry. Refer the following documentation for additional information:
Click on a property name to view additional details, including default values.
ProxyType
: string |connect-proxy
Debug
: bool |false
Patches
: list | requiredResourceFilter
: mapResourceType
: string | requiredTrafficDirection
: string | requiredServices
: list
Op
: string | requiredPath
: string | requiredValue
: map, number, boolean, or string
Complete configuration
When each field is defined, a property-override
configuration has the following form:
Specification
This section provides details about the fields you can configure for the property-override
extension.
ProxyType
Specifies the type of Envoy proxy that the extension applies to. The only supported value is connect-proxy
.
Values
- Default:
connect-proxy
- Data type: String
Debug
Enables full debug mode. When Debug
is set to true
, all possible fields for the given ResourceType
and first unmatched segment of Path
are returned on error. When set to false
, the error message only includes the first ten possible fields.
Values
- Default:
false
- Data type: Boolean
Patches[]
Specifies a list of one or more JSON Patches that map to the Envoy proxy configurations you want to modify. Refer to IETF RFC 6902 for information about the JSON Patch specification.
Values
- Default: None
- The
Patches
parameter is a list of configurations in JSON Patch format. Each patch can contain the following fields:
Patches[].ResourceFilter{}
Specifies the filter for targeting specific Envoy resources. The ResourceFilter
configuration is not part of the JSON Patch specification.
Values
- Default: None
- This field is required.
- Data type: Map
The following table describes how to configure a ResourceFilter
:
Parameter | Description | Type |
---|---|---|
ProxyType | Specifies the proxy type that the extension applies to. The only supported value is connect-proxy . | String |
ResourceType | Specifies the Envoy resource type that the extension applies to. You can specify one of the following values for each ResourceFilter :
| String |
TrafficDirection | Specifies the type of traffic that the extension applies to relative to the current proxy. You can specify one of the following values for each ResourceFilter :
| String |
Services | Specifies a list of services to target. Each member of the list has the following fields:
TrafficDirection is set to outbound , upstream services in this field correspond to local Envoy resources that Consul patches at runtime. Do not configure the Services is unset and if the local service is in transparent proxy mode. | List of maps |
Patches[].Op
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 byPath
with the given value. The JSON Patchadd
operation does not merge objects. To emulate merges, you must configure discreteadd
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 byPath
. 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
Patches[].Path
Specifies where the extension performs the associated operation on the specified resource type. Refer to ResourceType
for information about specifying a resource type to target. Refer to Op
for information about setting an operation to perform on the resources.
The Path
field does not support addressing array elements or protobuf map field entries. Refer to Constructing paths for information about how to construct paths.
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
- Default: None
- This field is required.
- Data type: String
Patches[].Value{}
Defines a value to set at the specified path if the operation 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 for additional guidance and to the Envoy API documentation 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 for additional information about wrappers.
Values
- Default: None
- This field is required if
Op
is set toadd
, otherwise you must omit the field. - This field takes one of the following data types:
- scalar
- enum
- map
Examples
The following examples demonstrate patterns that you may be able to model your configurations on.
Enable respect_dns_ttl
in a cluster
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
top-level field and Value
specifies a value of true
:
Update multiple values in a message field
In the following example, both ResourceFilter
blocks target the cluster corresponding to the other-svc
upstream service and modify Cluster /outlier_detection
properties:
The use of /seconds
in these examples corresponds to the same field in the google.protobuf.Duration 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
.
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:
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.