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:

• EnvoyExtensions in proxy defaults
• EnvoyExtensions in service defaults

Click on a property name to view additional details, including default values.

• ProxyType: string | connect-proxy
• Debug: bool | false
• Patches: list | required
  • ResourceFilter: map
    • ResourceType: string | required
    • TrafficDirection: string | required
    • Services: list
      • Name: string
      • Namespace: string | default | EnterpriseEnterprise
      • Partition: string | default | EnterpriseEnterprise
  • Op: string | required
  • Path: string | required
  • Value: map, number, boolean, or string

Complete configuration

When each field is defined, a property-override configuration has the following form:

ProxyType = "connect-proxy"
Debug = false
Patches = [
  {
    ResourceFilter = {
      ResourceType = "<type of resource>"
      TrafficDirection = "<inbound or outbound>"
      Services = [
        {
          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>"
    Value = "<values or map of field-values>"
  }
]

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:
  • ResourceFilter
  • Op
  • Path
  • Value

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:

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 by Path with the given value. The JSON Patch add operation does not merge objects. To emulate merges, you must configure discrete add 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 by Path. 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

• Default: None
• This field is required.
• Data type is one of the following string values:
  • add
  • remove

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 to add, 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:

Kind = "service-defaults"
Name = "my-svc"
Protocol = "http"
EnvoyExtensions = [
  {
    Name = "builtin/property-override",
    Arguments = {
      ProxyType = "connect-proxy",
      Patches = [
        {
          "ResourceFilter" = {
            "ResourceType" = "cluster",
            "TrafficDirection" = "outbound",
            "Service" = {
              "Name" = "other-svc"
            },
          },
          "Op" = "add",
          "Path" =  "/respect_dns_ttl",
          "Value" = 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:

Kind = "service-defaults"
Name = "my-svc"
Protocol = "http"
EnvoyExtensions = [
  {
    Name = "builtin/property-override",
    Arguments = {
      ProxyType = "connect-proxy",
      Patches = [
        {
          ResourceFilter = {
            ResourceType = "cluster"
            TrafficDirection = "outbound"
            Services = [{
              Name = "other-svc"
            }]
          }
          Op = "add"
          Path = "/outlier_detection/max_ejection_time/seconds"
          Value = 120
        },
        {
          ResourceFilter = {
            ResourceType = "cluster"
            TrafficDirection = "outbound"
            Services = [{
              Name = "other-svc"
            }]
          }
          Op = "add"
          Path = "/outlier_detection/max_ejection_time_jitter/seconds"
          Value = 1
        }
      ]
    }
  }
]

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:

Kind = "service-defaults"
Name = "my-svc"
Protocol = "http"
EnvoyExtensions = [
  {
    Name = "builtin/property-override"
    Arguments = {
      ProxyType = "connect-proxy"
      Patches = [
        {
          ResourceFilter = {
            ResourceType = "cluster"
            TrafficDirection = "outbound"
            Services = [{
              Name = "other-svc"
            }]
          }
          Op = "add"
          Path =  "/outlier_detection"
          Value = {
            "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.